ChemWiki - User contributions [en]

Mod:Hunt Research Group/Python scripts for cube files

2018-06-25T15:43:41Z

Ia2514:

[[File:ia2514_small_gif.gif|right]]

Getting Started
*go here for initial set-up [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CubePy_setup getting started]

The latest version of <code>CubePy</code>, along with a test cube file can be found [[:Media:CubePy_v1.1.zip|here]].

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

CubePy encompasses six modules that can be used to read, save, manipulate and visualise data from cube files:
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py ReadCube.py] - used to extract data from cube files and return it in convenient python formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py] - used to save data from cube files in convenient formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py CalculateCube.py] - used to manipulate data from cube files
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] - used to plot data from cube files (using [https://matplotlib.org Matplotlib])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] - used to plot data from cube files (using [http://docs.enthought.com/mayavi/mayavi/ Mayavi])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] - used to manipulate data not from cube files, but from files produced by the scripts above

If you want to save data from cube files
* for saving the values from the cube files, use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py]
* for saving histogram data, use the function <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] with <code>save=True</code>
* for saving a short summary file of the minimum, maximum and lowest curvature points on the van der Waals surface, use <code>save=True</code> when running <code>PlotSurface</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]

If you want to plot surfaces, isosurfaces, slices
* use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]. They are faster and better at 3D plotting than the equivalent functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]

If you want to generate static figures you can also consider using the 3D plotting functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]. These are especially recommended when wanting to display atoms as they look better than their [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] equivalents. However, keep in mind that Matplotlib sometimes fails at 3D rendering, which generates "incorrect" plots (i.e. elements that should be behind the rest of the plot appear at the front). Therefore, plots created using function from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] should be double-checked (by comparing them with plots from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py], by example).

If you want to plot histograms and KDEs
* use <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] to plot a histogram and/or KDE directly from cube files
* use <code>OverlapKDEs</code> and <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] to plot histograms and KDEs from files written by <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] when <code>save=True</code>

File:CubePy v1.1.zip

2018-06-25T15:43:20Z

Ia2514:

Mod:Hunt Research Group/AdditionalFunctions.py

2018-06-25T15:31:25Z

Ia2514: /* PlotHistogram */

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>AdditionalFunctions.py</code> is a collection of functions that do not work directly with cube files, but with data produced by the other scripts.

=Requirements=
* Python
* Matplotlib

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python AdditionalFunctions.py function_name file_path1 file_path2... arg1=val1 arg2=val2...</pre>

=Functions=
==OverlapKDEs==
[[File:ia2514_fig10.png|400px|right|thumb|Figure 1. Plot generated by OverlapKDEs]]
This function plots overlapping KDEs as read from _kde.out files written by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py#PlotHistogram <code>PlotHistogram</code>] from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>] (when <code>save</code> is True).

===Required arguments===

* <code>fpaths</code> (string) = paths for _kde.out files

===Optional arguments===
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python AdditionalFunctions.py OverlapKDEs NH3CH2Cl_esp_kde.out NH3CH2OH_esp_kde.out NH3CH2BH2_esp_kde.out xlim=[2,10]</pre>
The resulting plot is shown in figure 1.

==PlotHistogram==
This function plots one KDE and/or one histogram as read from _kde.out and _hist.out files written by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py#PlotHistogram <code>PlotHistogram</code>] from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>] (when <code>save</code> is True).

===Required arguments===
[[File:ia2514_fig5.png|400px|right|thumb|Figure 2. Plot generated by PlotHistogram]]
* <code>fpaths</code> (string) = paths for _kde.out and _hist.out files (should be one of each at most)

===Optional arguments===
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>cb_sym</code> (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (<code>cb_lim</code>, if specified, overrides <code>cb_sym</code>)

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])
* the function only works for one histogram file and/or one KDE file. If multiple files of either type are specified as arguments, the execution of the program is stopped and a warning is printed.
* the data in the files specified as arguments must be in the same units. If that is not the case, the execution of the program is stopped and a warning is printed.

===Example===
<pre>python AdditionalFunctions.py PlotHistogram test_emim_oac_esp_kde.out test_emim_oac_esp_hist.out</pre>
The resulting plot is shown in figure 2.

Mod:Hunt Research Group/PlotCube.py

2018-06-25T15:31:06Z

Ia2514: /* PlotHistogram */

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer/None/string, default=30) = the number of bins in the histogram (see [https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.histogram.html here] for details)
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values
* <code>cat</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>])
* <code>an</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>]; the atoms belonging to the anion are the remaining ones)
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>cb_sym</code> (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (<code>cb_lim</code>, if specified, overrides <code>cb_sym</code>)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-06-25T15:30:42Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python PlotCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>min_colour</code> (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>max_colour</code> (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>cb_sym</code> (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (<code>cb_lim</code>, if specified, overrides <code>cb_sym</code>)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>cb_sym</code> (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (<code>cb_lim</code>, if specified, overrides <code>cb_sym</code>)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>min_colour</code> (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>max_colour</code> (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>cb_sym</code> (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (<code>cb_lim</code>, if specified, overrides <code>cb_sym</code>)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>min_colour</code> (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>max_colour</code> (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>cb_sym</code> (boolean, default=False) = if True, the colour bar limits are chosen to be symmetric around 0 (<code>cb_lim</code>, if specified, overrides <code>cb_sym</code>)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-06-25T15:27:03Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python PlotCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>min_colour</code> (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>max_colour</code> (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>min_colour</code> (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>max_colour</code> (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name
* <code>min_colour</code> (list, default=[0,255,0]) = the RGB colour code of the minima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)
* <code>max_colour</code> (list, default=[255,0,252]) = the RGB colour code of the maxima (format: [float_red, float_green, float_blue] where float_red, float_green, float_blue are float numbers between 0 and 255)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/AdditionalFunctions.py

2018-06-25T15:23:11Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>AdditionalFunctions.py</code> is a collection of functions that do not work directly with cube files, but with data produced by the other scripts.

=Requirements=
* Python
* Matplotlib

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python AdditionalFunctions.py function_name file_path1 file_path2... arg1=val1 arg2=val2...</pre>

=Functions=
==OverlapKDEs==
[[File:ia2514_fig10.png|400px|right|thumb|Figure 1. Plot generated by OverlapKDEs]]
This function plots overlapping KDEs as read from _kde.out files written by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py#PlotHistogram <code>PlotHistogram</code>] from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>] (when <code>save</code> is True).

===Required arguments===

* <code>fpaths</code> (string) = paths for _kde.out files

===Optional arguments===
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python AdditionalFunctions.py OverlapKDEs NH3CH2Cl_esp_kde.out NH3CH2OH_esp_kde.out NH3CH2BH2_esp_kde.out xlim=[2,10]</pre>
The resulting plot is shown in figure 1.

==PlotHistogram==
This function plots one KDE and/or one histogram as read from _kde.out and _hist.out files written by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py#PlotHistogram <code>PlotHistogram</code>] from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>] (when <code>save</code> is True).

===Required arguments===
[[File:ia2514_fig5.png|400px|right|thumb|Figure 2. Plot generated by PlotHistogram]]
* <code>fpaths</code> (string) = paths for _kde.out and _hist.out files (should be one of each at most)

===Optional arguments===
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])
* the function only works for one histogram file and/or one KDE file. If multiple files of either type are specified as arguments, the execution of the program is stopped and a warning is printed.
* the data in the files specified as arguments must be in the same units. If that is not the case, the execution of the program is stopped and a warning is printed.

===Example===
<pre>python AdditionalFunctions.py PlotHistogram test_emim_oac_esp_kde.out test_emim_oac_esp_hist.out</pre>
The resulting plot is shown in figure 2.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-06-25T15:22:36Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python PlotCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube.py

2018-06-25T15:21:55Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer/None/string, default=30) = the number of bins in the histogram (see [https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.histogram.html here] for details)
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values
* <code>cat</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>])
* <code>an</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>]; the atoms belonging to the anion are the remaining ones)
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)
* <code>log</code> (boolean, default=True) = if True, it saves a .log file of the command used to run the functions (the command is tidied-up before saving i.e. unnecessary spaces are removed, argument values are converted to their usual uppercase/lowercase versions, file lists are explicit - instead of using wildcard symbols such as *)
* <code>logfile</code> (string, default=None) = the name of the log file (if <code>log</code> is True); by default the file name is the input file name followed by the function name

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-06-25T15:14:51Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python PlotCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube.py

2018-06-25T15:13:54Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer/None/string, default=30) = the number of bins in the histogram (see [https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.histogram.html here] for details)
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values
* <code>cat</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>])
* <code>an</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>]; the atoms belonging to the anion are the remaining ones)
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/ReadCube.py

2018-06-25T15:12:37Z

Ia2514: /* GetVdWPoints */

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>ReadCube.py</code> is a collection of functions that extract data from cube files and return it in convenient python formats. These are the main functions used by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>], [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py <code>PlotCube_mayavi.py</code>], [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py <code>SaveCube.py</code>] and [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>].

=Requirements=
* Python

An easy way to obtain Python is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
If you want to use the functions in <code>ReadCube.py</code> to extract data from cube files in Python, you will need to write a Python script:
<pre>
import ReadCube as rc
var1 = rc.function_name(arg1=val1, arg2=val2,...)
<do something with var1: print it, save it to file, etc.>
</pre>

The Python script can be written and ran in different ways:
* as a new .py file using Spyder (Spyder <math>\rightarrow</math> File <math>\rightarrow</math> New file... <math>\rightarrow</math> [write the file] <math>\rightarrow</math> Save As... [make sure you save the file in the same directory as <code>ReadCube.py</code>] <math>\rightarrow</math> Run <math>\rightarrow</math> Run [the file will be run in the iPython console]
* in the IPython console in Spyder: write the Python commands directly in the console, but make sure that the current working directory is the one containing <code>ReadCube.py</code>
* in the terminal window: type <code>ipython</code>, then write the Python commands directly in the terminal, but make sure that the current working directory is the one containing <code>ReadCube.py</code>

===Example===
<pre>
import ReadCube as rc
at = rc.Atoms(fpath='test_emim_oac_esp.cube')
print([i[0] for i in at])
</pre>
This example prints the atomic numbers of all the constituent atoms:
<pre>
[7, 6, 1, 1, 1, 6, 1, 7, 6, 1, 1, 6, 1, 1, 1, 6, 6, 1, 1, 6, 8, 8, 6, 1, 1, 1]
</pre>

=Functions=
==ExtractData==
This function extracts all the data from the cube file.

===Required parameters===
* <code>fpath</code> (string) = path for a cube file

===Optional parameters===
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Returns===
a list of: the number of atoms, a list of the coordinates of the origin, the number of values recorded at each point, the number of voxels along x axis, a list of the coordinates of the increment vector for the x axis, the number of voxels along y axis, a list of the coordinates of the increment vector for the y axis, the number of voxels along z axis, a list of the coordinates of the increment vector for the z axis, a list of lists containing the atomic number, the nuclear charge and coordinates for each atom, a list of MO indices, a 3D array of all the values in the cube file, a list of all the values in the cube file, value units (in order)

==Atoms==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>value_type</code> (string, default='esp') = value type
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom

==Axes==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>n_x</code> (integer, default=None) = number of voxels along x axis
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>n_y</code> (integer, default=None) = number of voxels along y axis
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>n_z</code> (integer, default=None) = number of voxels along z axis
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)

===Returns===
a list of three lists representing the x, y and z coordinates, respectively of the grid points

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>origin, n_x, x_vector, n_y, y_vector, n_z, z_vector</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==ValuesAsMatrix==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a 3D array of all the values in the cube file

==ValuesAsList==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a list of all the values in the cube file (in the order in which they appear)

==ValuesAsDictionary==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)

===Returns===
a list of an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value and an ordered dictionary of each grid point (represented through a tuple of its indices) and its corresponding value

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>vals, axes_list, origin</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==Minimum==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list the coordinates of all the grid points that have the minimum value

===Observations===

* called with either <code>fpath, au, density, value_type, units</code> or <code>gridpts, vals</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==Maximum==

* <code>fpath</code> (string, default=None) = path for a cube file
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list the coordinates of all the grid points that have the maximum value

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>gridpts, vals</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==GetVdWPoints==
This function returns all the points that are close to the surface defined in terms of the Van der Waals radii of the constituent atoms.

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>atoms_list</code> (list, default=None) = a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Atoms <code>Atoms</code>])
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>cat</code> (boolean, default=False) = if True, it only selects the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside the code)
* <code>an</code> (boolean, default=False) = if True, it only selects the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside the code; the atoms belonging to the anion are the remaining ones)
* <code>thickness</code> (float, default=0.3) = represents the fractional thickness of the van der Waals surface (by default, the points that are within 0.3=30% of the surface defined by the van der Waals radii of the constituent atoms are selected as part of the van der Waals surface)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list of three lists: the first one contains the x, y, z coordinates and the value of each point on the VdW surface, the second one contains the indices and the value of each point on the VdW surface and the third one contains the coordinates and values of all the points that are on or inside the VdW surface

===Observations===
* called with either <code>fpath, au, density, value_type, units, factor</code> or <code>axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, origin, factor</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).
* the points that reside on the VdW surface are chosen to be within plus/minus a distance of the surface defined by the Van der Waals radii of the constituent atoms (the distance is given by the distance between two diagonally adjacent points in the grid multiplied by <code>thickness</code>)
* if you want to only select certain points from the van der Waals surface, you can change this manually inside the code; this also applies for only selecting points which belong to either the cation or the anion (for which there are the parameters <code>cat</code> and <code>an</code>, respectively)

Mod:Hunt Research Group/Python scripts for cube files

2018-06-25T14:53:06Z

Ia2514:

[[File:ia2514_small_gif.gif|right]]

Getting Started
*go here for initial set-up [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CubePy_setup getting started]

The latest version of <code>CubePy</code>, along with a test cube file can be found [[:Media:CubePy_v1.zip|here]].

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

CubePy encompasses six modules that can be used to read, save, manipulate and visualise data from cube files:
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py ReadCube.py] - used to extract data from cube files and return it in convenient python formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py] - used to save data from cube files in convenient formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py CalculateCube.py] - used to manipulate data from cube files
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] - used to plot data from cube files (using [https://matplotlib.org Matplotlib])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] - used to plot data from cube files (using [http://docs.enthought.com/mayavi/mayavi/ Mayavi])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] - used to manipulate data not from cube files, but from files produced by the scripts above

If you want to save data from cube files
* for saving the values from the cube files, use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py]
* for saving histogram data, use the function <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] with <code>save=True</code>
* for saving a short summary file of the minimum, maximum and lowest curvature points on the van der Waals surface, use <code>save=True</code> when running <code>PlotSurface</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]

If you want to plot surfaces, isosurfaces, slices
* use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]. They are faster and better at 3D plotting than the equivalent functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]

If you want to generate static figures you can also consider using the 3D plotting functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]. These are especially recommended when wanting to display atoms as they look better than their [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] equivalents. However, keep in mind that Matplotlib sometimes fails at 3D rendering, which generates "incorrect" plots (i.e. elements that should be behind the rest of the plot appear at the front). Therefore, plots created using function from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] should be double-checked (by comparing them with plots from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py], by example).

If you want to plot histograms and KDEs
* use <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] to plot a histogram and/or KDE directly from cube files
* use <code>OverlapKDEs</code> and <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] to plot histograms and KDEs from files written by <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] when <code>save=True</code>

Mod:Hunt Research Group/Python scripts for cube files

2018-06-25T14:50:32Z

Ia2514:

Getting Started
*go here for initial set-up [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CubePy_setup getting started]

The latest version of <code>CubePy</code>, along with a test cube file can be found [[:Media:CubePy_v1.zip|here]].

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

[[File:ia2514_small_gif.gif|400px|right|thumb|Click on this gif to see a 360° plot generated using PlotSurface from PlotCube_mayavi]]

CubePy encompasses six modules that can be used to read, save, manipulate and visualise data from cube files:
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py ReadCube.py] - used to extract data from cube files and return it in convenient python formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py] - used to save data from cube files in convenient formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py CalculateCube.py] - used to manipulate data from cube files
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] - used to plot data from cube files (using [https://matplotlib.org Matplotlib])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] - used to plot data from cube files (using [http://docs.enthought.com/mayavi/mayavi/ Mayavi])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] - used to manipulate data not from cube files, but from files produced by the scripts above

If you want to save data from cube files
* for saving the values from the cube files, use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py]
* for saving histogram data, use the function <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] with <code>save=True</code>
* for saving a short summary file of the minimum, maximum and lowest curvature points on the van der Waals surface, use <code>save=True</code> when running <code>PlotSurface</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]

If you want to plot surfaces, isosurfaces, slices
* use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]. They are faster and better at 3D plotting than the equivalent functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]

If you want to generate static figures you can also consider using the 3D plotting functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]. These are especially recommended when wanting to display atoms as they look better than their [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] equivalents. However, keep in mind that Matplotlib sometimes fails at 3D rendering, which generates "incorrect" plots (i.e. elements that should be behind the rest of the plot appear at the front). Therefore, plots created using function from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] should be double-checked (by comparing them with plots from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py], by example).

If you want to plot histograms and KDEs
* use <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] to plot a histogram and/or KDE directly from cube files
* use <code>OverlapKDEs</code> and <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] to plot histograms and KDEs from files written by <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] when <code>save=True</code>

Mod:Hunt Research Group/Python scripts for cube files

2018-06-25T14:48:27Z

Ia2514:

Getting Started
*go here for initial set-up [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CubePy_setup getting started]

The latest version of <code>CubePy</code>, along with a test cube file can be found [[:Media:CubePy_v1.zip|here]].

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

[[File:ia2514_small_gif.gif|400px|right|thumb]]

CubePy encompasses six modules that can be used to read, save, manipulate and visualise data from cube files:
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py ReadCube.py] - used to extract data from cube files and return it in convenient python formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py] - used to save data from cube files in convenient formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py CalculateCube.py] - used to manipulate data from cube files
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] - used to plot data from cube files (using [https://matplotlib.org Matplotlib])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] - used to plot data from cube files (using [http://docs.enthought.com/mayavi/mayavi/ Mayavi])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] - used to manipulate data not from cube files, but from files produced by the scripts above

If you want to save data from cube files
* for saving the values from the cube files, use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py]
* for saving histogram data, use the function <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] with <code>save=True</code>
* for saving a short summary file of the minimum, maximum and lowest curvature points on the van der Waals surface, use <code>save=True</code> when running <code>PlotSurface</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]

If you want to plot surfaces, isosurfaces, slices
* use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]. They are faster and better at 3D plotting than the equivalent functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]

If you want to generate static figures you can also consider using the 3D plotting functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]. These are especially recommended when wanting to display atoms as they look better than their [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] equivalents. However, keep in mind that Matplotlib sometimes fails at 3D rendering, which generates "incorrect" plots (i.e. elements that should be behind the rest of the plot appear at the front). Therefore, plots created using function from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] should be double-checked (by comparing them with plots from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py], by example).

If you want to plot histograms and KDEs
* use <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] to plot a histogram and/or KDE directly from cube files
* use <code>OverlapKDEs</code> and <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] to plot histograms and KDEs from files written by <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] when <code>save=True</code>

File:Ia2514 small gif.gif

2018-06-25T14:47:17Z

Ia2514:

Mod:Hunt Research Group/PlotCube mayavi.py

2018-06-13T12:56:24Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python PlotCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-06-11T10:01:39Z

Ia2514: /* Instructions */

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python PlotCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/Python scripts for cube files

2018-05-17T11:42:19Z

Ia2514:

The latest version of <code>CubePy</code>, along with a test cube file can be found [[:Media:CubePy_v1.zip|here]].

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

CubePy encompasses six modules that can be used to read, save, manipulate and visualise data from cube files:
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py ReadCube.py] - used to extract data from cube files and return it in convenient python formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py] - used to save data from cube files in convenient formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py CalculateCube.py] - used to manipulate data from cube files
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] - used to plot data from cube files (using [https://matplotlib.org Matplotlib])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] - used to plot data from cube files (using [http://docs.enthought.com/mayavi/mayavi/ Mayavi])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] - used to manipulate data not from cube files, but from files produced by the scripts above

If you want to save data from cube files
* for saving the values from the cube files, use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py]
* for saving histogram data, use the function <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] with <code>save=True</code>
* for saving a short summary file of the minimum, maximum and lowest curvature points on the van der Waals surface, use <code>save=True</code> when running <code>PlotSurface</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]

If you want to plot surfaces, isosurfaces, slices
* use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]. They are faster and better at 3D plotting than the equivalent functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]

If you want to generate static figures you can also consider using the 3D plotting functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]. These are especially recommended when wanting to display atoms as they look better than their [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] equivalents. However, keep in mind that Matplotlib sometimes fails at 3D rendering, which generates "incorrect" plots (i.e. elements that should be behind the rest of the plot appear at the front). Therefore, plots created using function from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] should be double-checked (by comparing them with plots from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py], by example).

If you want to plot histograms and KDEs
* use <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] to plot a histogram and/or KDE directly from cube files
* use <code>OverlapKDEs</code> and <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] to plot histograms and KDEs from files written by <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] when <code>save=True</code>

File:CubePy v1.zip

2018-05-17T11:39:15Z

Ia2514:

Mod:Hunt Research Group/Python scripts for cube files

2018-05-10T19:11:17Z

Ia2514:

The latest version of <code>CubePy</code>, along with a test cube file can be found [[:Media:CubePy.zip|here]].

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

CubePy encompasses six modules that can be used to read, save, manipulate and visualise data from cube files:
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py ReadCube.py] - used to extract data from cube files and return it in convenient python formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py] - used to save data from cube files in convenient formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py CalculateCube.py] - used to manipulate data from cube files
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] - used to plot data from cube files (using [https://matplotlib.org Matplotlib])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] - used to plot data from cube files (using [http://docs.enthought.com/mayavi/mayavi/ Mayavi])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] - used to manipulate data not from cube files, but from files produced by the scripts above

If you want to save data from cube files
* for saving the values from the cube files, use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py]
* for saving histogram data, use the function <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] with <code>save=True</code>
* for saving a short summary file of the minimum, maximum and lowest curvature points on the van der Waals surface, use <code>save=True</code> when running <code>PlotSurface</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]

If you want to plot surfaces, isosurfaces, slices
* use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]. They are faster and better at 3D plotting than the equivalent functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]

If you want to generate static figures you can also consider using the 3D plotting functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]. These are especially recommended when wanting to display atoms as they look better than their [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] equivalents. However, keep in mind that Matplotlib sometimes fails at 3D rendering, which generates "incorrect" plots (i.e. elements that should be behind the rest of the plot appear at the front). Therefore, plots created using function from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] should be double-checked (by comparing them with plots from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py], by example).

If you want to plot histograms and KDEs
* use <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] to plot a histogram and/or KDE directly from cube files
* use <code>OverlapKDEs</code> and <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] to plot histograms and KDEs from files written by <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] when <code>save=True</code>

File:CubePy.zip

2018-05-10T19:10:24Z

Ia2514:

Mod:Hunt Research Group/AdditionalFunctions.py

2018-05-10T16:24:36Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>AdditionalFunctions.py</code> is a collection of functions that do not work directly with cube files, but with data produced by the other scripts.

=Requirements=
* Python
* Matplotlib

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python AdditionalFunctions.py function_name file_path1 file_path2... arg1=val1 arg2=val2...</pre>

=Functions=
==OverlapKDEs==
[[File:ia2514_fig10.png|400px|right|thumb|Figure 1. Plot generated by OverlapKDEs]]
This function plots overlapping KDEs as read from _kde.out files written by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py#PlotHistogram <code>PlotHistogram</code>] from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>] (when <code>save</code> is True).

===Required arguments===

* <code>fpaths</code> (string) = paths for _kde.out files

===Optional arguments===
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python AdditionalFunctions.py OverlapKDEs NH3CH2Cl_esp_kde.out NH3CH2OH_esp_kde.out NH3CH2BH2_esp_kde.out xlim=[2,10]</pre>
The resulting plot is shown in figure 1.

==PlotHistogram==
This function plots one KDE and/or one histogram as read from _kde.out and _hist.out files written by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py#PlotHistogram <code>PlotHistogram</code>] from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>] (when <code>save</code> is True).

===Required arguments===
[[File:ia2514_fig5.png|400px|right|thumb|Figure 2. Plot generated by PlotHistogram]]
* <code>fpaths</code> (string) = paths for _kde.out and _hist.out files (should be one of each at most)

===Optional arguments===
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])
* the function only works for one histogram file and/or one KDE file. If multiple files of either type are specified as arguments, the execution of the program is stopped and a warning is printed.
* the data in the files specified as arguments must be in the same units. If that is not the case, the execution of the program is stopped and a warning is printed.

===Example===
<pre>python AdditionalFunctions.py PlotHistogram test_emim_oac_esp_kde.out test_emim_oac_esp_hist.out</pre>
The resulting plot is shown in figure 2.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T16:24:27Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube.py

2018-05-10T16:24:16Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer/None/string, default=30) = the number of bins in the histogram (see [https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.histogram.html here] for details)
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values
* <code>cat</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>])
* <code>an</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>]; the atoms belonging to the anion are the remaining ones)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/CalculateCube.py

2018-05-10T16:24:07Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>CalculateCube.py</code> is a collection of functions that manipulate data from cube files.

=Requirements=
* Python
* NumPy
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
If you want to use the functions in <code>CalculateCube.py</code> to extract data from cube files in Python, you will need to write a Python script:
<pre>
import CalculateCube as cc
var1 = cc.function_name(arg1=val1, arg2=val2,...)
<do something with var1: print it, save it to file, etc.>
</pre>

The Python script can be written and ran in different ways:
* as a new .py file using Spyder (Spyder <math>\rightarrow</math> File <math>\rightarrow</math> New file... <math>\rightarrow</math> [write the file] <math>\rightarrow</math> Save As... [make sure you save the file in the same directory as <code>CalculateCube.py</code>] <math>\rightarrow</math> Run <math>\rightarrow</math> Run [the file will be run in the iPython console]
* in the IPython console in Spyder: write the Python commands directly in the console, but make sure that the current working directory is the one containing <code>CalculateCube.py</code>
* in the terminal window: type <code>ipython</code>, then write the Python commands directly in the terminal, but make sure that the current working directory is the one containing <code>CalculateCube.py</code>

=Functions=
==Derivative==
This function returns the Nth derivative of the value matrix from a cube file.

===Arguments===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>val</code> (list, default=None) = a matrix of all the values
* <code>order</code> (integer, default=1) = the order of the derivative
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if <code>fpath</code> is specified)

===Returns===
a list of two lists: the first one of three arrays corresponding to the derivatives of the value matrix with respect to x, y and z (each array has the same shape as the original matrix) and the second one of the dx, dy and dz values (i.e. the lengths of the x, y and z increment vectors)

===Observations===
* called with either <code>fpath, order, au, density, value_type, units</code> or <code>x_vector, y_vector, z_vector, val, order</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

===Example===
<pre>
import CalculateCube as cc
d2 = cc.Derivative(fpath='test_emim_oac_esp.cube',order=2)
print(d2[0][0][0][0][0])</pre>

This example calculates the second order derivative for the values in test_emim_oac_esp.cube and prints the first one to screen:

<pre>-0.0022345003728754002</pre>

==Laplacian==
This function calculates the Laplacian by summing the second order derivative with respect to x, y and z as obtained using [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#Derivative <code>Derivative</code>] for each data point.

===Arguments===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>val</code> (list, default=None) = a matrix of all the values
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#Derivative <code>Derivative</code>]

===Returns===
a matrix of the Laplacian for every data point from a cube file

===Observations===
* called with either <code>fpath, order, au, density, value_type, units</code> or <code>x_vector, y_vector, z_vector, val, order</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

===Example===
<pre>
import CalculateCube as cc
l = cc.Laplacian(fpath='test_emim_oac_esp.cube')
print(l[0][0][0])</pre>

This example calculates the Laplacian for the values in test_emim_oac_esp.cube and prints the first one to screen:

<pre>-0.000563911766024</pre>

==VdWLaplacian==

===Arguments===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>atoms_list</code> (list, default=None) = a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Atoms <code>Atoms</code>])
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>val</code> (list, default=None) = a matrix of all the values
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>vdw_ind</code> (list, default=None) = a list of lists containing the indices and the values of the points close to the van der Waals surface
* <code>vdw_pts</code> (list, default=None) = a list of lists containing the coordinates and the values of the points close to the van der Waals surface
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if either <code>vdw_ind</code> or <code>vdw_pts</code> is not specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if either <code>vdw_ind</code> or <code>vdw_pts</code> is not specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if either <code>vdw_ind</code> or <code>vdw_pts</code> is not specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#Laplacian <code>Laplacian</code>]

===Returns===
two lists: one containing coordinates + Laplacian for each data point on the van der Waals surface and one containing indices + Laplacian for each data point on the van der Waals surface

===Observations===
* called with <code>fpath, factor, au, density, value_type, units</code>, <code>fpath, factor, vdw_ind, vdw_pts, au, density, value_type, units</code>, <code>axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, val, factor</code> or <code>axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, val, factor, vdw_ind, vdw_pts</code>

* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

===Example===
<pre>
import CalculateCube as cc
vdwl = cc.VdWLaplacian(fpath='test_emim_oac_esp.cube')
print(vdwl[0][0][3])</pre>

This example calculates the Laplacian for the van der Waals surface values in test_emim_oac_esp.cube and prints the first one to screen:

<pre>2.5970251494598204</pre>

==Hessian==

===Arguments===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>val</code> (list, default=None) = a matrix of all the values
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#Derivative <code>Derivative</code>]

===Returns===
a matrix of the Hessian for every data point from a cube file

===Observations===
* called with either <code>fpath, order, au, density, value_type, units</code> or <code>x_vector, y_vector, z_vector, val, order</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

===Example===
<pre>
import CalculateCube as cc
h = cc.Hessian(fpath='test_emim_oac_esp.cube', density=3)
for i in range(3):
print([h[0][0][0][i][j] for j in range(3)])</pre>

This example calculates the hessian for the values in test_emim_oac_esp.cube at a reduced density and prints the first one to screen:

<pre>[-0.002701294001419571, 0.0068108009963301665, 0.006906352712240404]
[0.0068108009963301708, 0.0013040459589339015, 0.01042453556361086]
[0.0069063527122403996, 0.010424535563610851, -0.00046992647168781301]</pre>

==VdWHessian==
===Arguments===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>atoms_list</code> (list, default=None) = a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Atoms <code>Atoms</code>])
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>val</code> (list, default=None) = a matrix of all the values* <code>factor</code> (float, default=1) = * <code>vdw_ind</code> (list, default=None) = a list of lists containing the indices and the values of the points close to the van der Waals surface* <code>vdw_pts</code> (list, default=None) = a list of lists containing the coordinates and the values of the points close to the van der Waals surface
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===

* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if <code>fpath</code> is specified)* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if either <code>vdw_ind</code> or <code>vdw_pts</code> is not specified)* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if either <code>vdw_ind</code> or <code>vdw_pts</code> is not specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]; if either <code>vdw_ind</code> or <code>vdw_pts</code> is not specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#Hessian <code>Hessian</code>]

===Returns===

two lists: one containing coordinates + Hessian matrix for each data point on the van der Waals surface and one containing indices + Hessian matrix for each data point on the van der Waals surface

===Observations===
* called with <code>fpath, factor, au, density, value_type, units</code>, <code>fpath, factor, vdw_ind, vdw_pts, au, density, value_type, units</code>, <code>axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, val, factor</code> or <code>axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, val, factor, vdw_ind, vdw_pts</code>

* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

===Example===
<pre>
import CalculateCube as cc
vdwh = cc.VdWHessian(fpath='test_emim_oac_esp.cube')
print(vdwh[0][0][3])</pre>

This example calculates the hessian for the van der Waals surface values in test_emim_oac_esp.cube and prints the first one to screen:

<pre>[[6.2995640717272767, 3.0272898269372841, -0.043632672896223364],
[3.0272898269372845, -1.268343295247532, 0.057448511163856956],
[-0.043632672896223711, 0.057448511163856707, -2.4341956270199243]]</pre>

Mod:Hunt Research Group/SaveCube.py

2018-05-10T16:23:56Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>SaveCube.py</code> is a collection of functions that save the data from cube files in convenient formats.

=Requirements=
* Python
* [https://pandas.pydata.org pandas]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
The saving functions can be run from the terminal window by typing:
<pre>python SaveCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==SaveAll==
This function writes the x, y, z coordinates and the values from a cube file to a new file (4 columns).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>outfile</code> (string, default=None) = path for the output file (if None, the script used the input filename with the extension ".csv"
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* very slow if run for all the points in a cube file
* the script predicts the size of the file (which is also an indication of the running time) and it allows the user to:
# Proceed
# Reduce the number of points then proceed
# Abort
* if the user selects option number 2, they will be asked to input an integer number n so that only every nth value is saved to the file. Afterwards, the scripts prints the new predicted size and allows the user to once again select between options 1, 2 and 3.

===Example===
<pre>python SaveCube.py SaveAll test_emim_oac_esp.cube outfile='emim_oac_all.csv'</pre>

This example will raise the follow message:

<pre>Your file size will be 34MB. Options: 1. Proceed 2. Reduce the number of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to reduce the number of points (by typing in 2 then enter), a new message will be printed:

<pre>Please input an integer number n so that only every n value is saved to the file:</pre>

If the user inputs the number 100 (by typing 100 then enter), the new message will be:

<pre>Your file size will be 340KB. Options: 1. Proceed 2. Reduce the number of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to proceed (by typing in 1 then enter), the new emim_oac_all.csv file should be:

<pre> X coord/A Y coord/A Z coord/A Value/V
-6.342285 -6.155011 -3.804660 1.98280E-01
-6.342285 -6.016080 2.169381 2.57662E-01
-6.342285 -5.738218 0.224345 3.08147E-01
-6.342285 -5.460355 -1.720692 2.99211E-01
-6.342285 -5.182493 -3.665729 2.39004E-01
...</pre>

==SaveVdW==
This function writes the x, y, z coordinates and the values of all the points that lie on a surface defined by the van der Waals radii of the atoms to a new file (4 columns).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>outfile</code> (string, default=None) = path for the output file (if None, the script used the input filename with the extension ".csv"
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* the script predicts the size of the file (which is also an indication of the running time) and it allows the user to:
# Proceed
# Reduce the number of points then proceed
# Abort
* if the user selects option number 2, they will be asked to input an integer number n so that only every nth value is saved to the file. Afterwards, the scripts prints the new predicted size and allows the user to once again select between options 1, 2 and 3.

===Example===
<pre>python SaveCube.py SaveVdW test_emim_oac_esp.cube outfile='emim_oac_vdw_dens2.csv' density=2</pre>

This example will raise the follow message:

<pre>Your file size will be 18KB. Options: 1. Proceed 2. Reduce the number of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to proceed (by typing in 1 then enter), the new emim_oac_vdw_dens2.csv file should be:

<pre> X coord/A Y coord/A Z coord/A Value/V
-4.952973 -0.875626 0.085413 1.88899E+00
-4.952973 -0.875626 0.363276 1.98856E+00
-4.952973 -0.875626 0.641138 1.90018E+00
-4.952973 -0.597764 -0.192449 1.72317E+00
-4.952973 -0.597764 0.085413 2.00726E+00
...</pre>

Mod:Hunt Research Group/ReadCube.py

2018-05-10T16:23:47Z

Ia2514:

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

<code>ReadCube.py</code> is a collection of functions that extract data from cube files and return it in convenient python formats. These are the main functions used by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>], [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py <code>PlotCube_mayavi.py</code>], [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py <code>SaveCube.py</code>] and [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>].

=Requirements=
* Python

An easy way to obtain Python is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
If you want to use the functions in <code>ReadCube.py</code> to extract data from cube files in Python, you will need to write a Python script:
<pre>
import ReadCube as rc
var1 = rc.function_name(arg1=val1, arg2=val2,...)
<do something with var1: print it, save it to file, etc.>
</pre>

The Python script can be written and ran in different ways:
* as a new .py file using Spyder (Spyder <math>\rightarrow</math> File <math>\rightarrow</math> New file... <math>\rightarrow</math> [write the file] <math>\rightarrow</math> Save As... [make sure you save the file in the same directory as <code>ReadCube.py</code>] <math>\rightarrow</math> Run <math>\rightarrow</math> Run [the file will be run in the iPython console]
* in the IPython console in Spyder: write the Python commands directly in the console, but make sure that the current working directory is the one containing <code>ReadCube.py</code>
* in the terminal window: type <code>ipython</code>, then write the Python commands directly in the terminal, but make sure that the current working directory is the one containing <code>ReadCube.py</code>

===Example===
<pre>
import ReadCube as rc
at = rc.Atoms(fpath='test_emim_oac_esp.cube')
print([i[0] for i in at])
</pre>
This example prints the atomic numbers of all the constituent atoms:
<pre>
[7, 6, 1, 1, 1, 6, 1, 7, 6, 1, 1, 6, 1, 1, 1, 6, 6, 1, 1, 6, 8, 8, 6, 1, 1, 1]
</pre>

=Functions=
==ExtractData==
This function extracts all the data from the cube file.

===Required parameters===
* <code>fpath</code> (string) = path for a cube file

===Optional parameters===
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Returns===
a list of: the number of atoms, a list of the coordinates of the origin, the number of values recorded at each point, the number of voxels along x axis, a list of the coordinates of the increment vector for the x axis, the number of voxels along y axis, a list of the coordinates of the increment vector for the y axis, the number of voxels along z axis, a list of the coordinates of the increment vector for the z axis, a list of lists containing the atomic number, the nuclear charge and coordinates for each atom, a list of MO indices, a 3D array of all the values in the cube file, a list of all the values in the cube file, value units (in order)

==Atoms==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>value_type</code> (string, default='esp') = value type
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom

==Axes==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>n_x</code> (integer, default=None) = number of voxels along x axis
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>n_y</code> (integer, default=None) = number of voxels along y axis
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>n_z</code> (integer, default=None) = number of voxels along z axis
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)

===Returns===
a list of three lists representing the x, y and z coordinates, respectively of the grid points

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>origin, n_x, x_vector, n_y, y_vector, n_z, z_vector</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==ValuesAsMatrix==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a 3D array of all the values in the cube file

==ValuesAsList==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a list of all the values in the cube file (in the order in which they appear)

==ValuesAsDictionary==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)

===Returns===
a list of an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value and an ordered dictionary of each grid point (represented through a tuple of its indices) and its corresponding value

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>vals, axes_list, origin</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==Minimum==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list the coordinates of all the grid points that have the minimum value

===Observations===

* called with either <code>fpath, au, density, value_type, units</code> or <code>gridpts, vals</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==Maximum==

* <code>fpath</code> (string, default=None) = path for a cube file
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list the coordinates of all the grid points that have the maximum value

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>gridpts, vals</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==GetVdWPoints==
This function returns all the points that are close to the surface defined in terms of the Van der Waals radii of the constituent atoms.

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>atoms_list</code> (list, default=None) = a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Atoms <code>Atoms</code>])
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>cat</code> (boolean, default=False) = if True, it only selects the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside the code)
* <code>an</code> (boolean, default=False) = if True, it only selects the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside the code; the atoms belonging to the anion are the remaining ones)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list of three lists: the first one contains the x, y, z coordinates and the value of each point on the VdW surface, the second one contains the indices and the value of each point on the VdW surface and the third one contains the coordinates and values of all the points that are on or inside the VdW surface

===Observations===
* called with either <code>fpath, au, density, value_type, units, factor</code> or <code>axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, origin, factor</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).
* the points that reside on the VdW surface are chosen to be within plus/minus a fractional distance of the surface defined by the Van der Waals radii of the constituent atoms (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid)
* if you want to only select certain points from the van der Waals surface, you can change this manually inside the code; this also applies for only selecting points which belong to either the cation or the anion (for which there are the parameters <code>cat</code> and <code>an</code>, respectively)

Mod:Hunt Research Group/Python scripts for cube files

2018-05-10T16:23:13Z

Ia2514:

The latest version of <code>CubePy</code>, along with a test cube file can be found [[:Media:OxanaAndriuc_23Apr_2018_Code.zip|here]].

CubePy is under [https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode CC BY-NC-SA license]

CubePy encompasses six modules that can be used to read, save, manipulate and visualise data from cube files:
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py ReadCube.py] - used to extract data from cube files and return it in convenient python formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py] - used to save data from cube files in convenient formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py CalculateCube.py] - used to manipulate data from cube files
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] - used to plot data from cube files (using [https://matplotlib.org Matplotlib])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] - used to plot data from cube files (using [http://docs.enthought.com/mayavi/mayavi/ Mayavi])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] - used to manipulate data not from cube files, but from files produced by the scripts above

If you want to save data from cube files
* for saving the values from the cube files, use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py]
* for saving histogram data, use the function <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] with <code>save=True</code>
* for saving a short summary file of the minimum, maximum and lowest curvature points on the van der Waals surface, use <code>save=True</code> when running <code>PlotSurface</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]

If you want to plot surfaces, isosurfaces, slices
* use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]. They are faster and better at 3D plotting than the equivalent functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]

If you want to generate static figures you can also consider using the 3D plotting functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]. These are especially recommended when wanting to display atoms as they look better than their [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] equivalents. However, keep in mind that Matplotlib sometimes fails at 3D rendering, which generates "incorrect" plots (i.e. elements that should be behind the rest of the plot appear at the front). Therefore, plots created using function from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] should be double-checked (by comparing them with plots from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py], by example).

If you want to plot histograms and KDEs
* use <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] to plot a histogram and/or KDE directly from cube files
* use <code>OverlapKDEs</code> and <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] to plot histograms and KDEs from files written by <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] when <code>save=True</code>

Mod:Hunt Research Group/PlotCube.py

2018-05-10T15:43:01Z

Ia2514: /* Optional arguments */

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer/None/string, default=30) = the number of bins in the histogram (see [https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.histogram.html here] for details)
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values
* <code>cat</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>])
* <code>an</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>]; the atoms belonging to the anion are the remaining ones)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T15:42:59Z

Ia2514: /* Optional arguments */

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T15:37:54Z

Ia2514: /* Calls */

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T15:36:24Z

Ia2514: /* Calls */

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T15:34:43Z

Ia2514: /* Optional arguments */

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. iso±0.01 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T15:28:01Z

Ia2514: /* Optional arguments */

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted in colour
* <code>iso_range</code> (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None)
* <code>iso_range</code> (float, default=0.01) =
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T15:27:03Z

Ia2514: /* Calls */

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
*iso (float, default=None) = the value of the points to be plotted in colour
*iso_range (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None)
* <code>iso_range</code> (float, default=0.01) =
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T15:23:47Z

Ia2514: /* Optional arguments */

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
*iso (float, default=None) = the value of the points to be plotted in colour
*iso_range (float, default=0.05) = the value range to consider when selecting the points (i.e. iso±0.05 by default)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None)
* <code>iso_range</code> (float, default=0.01) =
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/PlotCube mayavi.py

2018-05-10T15:18:17Z

Ia2514: /* Optional arguments */

<code>PlotCube_mayavi.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* [http://docs.enthought.com/mayavi/mayavi/ mayavi]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain mayavi is by installing [https://www.enthought.com/product/canopy/ Canopy].

Open Canopy <math>\rightarrow</math> Tools <math>\rightarrow</math> Canopy Terminal

Using the Canopy Terminal allows the user to use the Canopy Python without making it the default one.

=Instructions=
==Running the code==
The plotting functions can be run from the Canopy terminal window by typing:

<pre>python ReadCube_mayavi.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

==Interacting with the plot==
Once the Mayavi Scene window is open, you can change plot settings by clicking on 'View the Mayavi pipeline'. This will open a new window where you will be able to see and modify the different layers of the plot.

===Changing the colour scheme===
Find the desired layer within the list, click on Colors and legends <math>\rightarrow</math> Scalar LUT <math>\rightarrow</math> Out mode

===Changing the transparency===
Click on the desired element in the list <math>\rightarrow</math> Actor <math>\rightarrow</math> Actor <math>\rightarrow</math> Opacity

===Showing/Hiding an element===
This can be done either by changing the opacity or by right-clicking on the desired element <math>\rightarrow</math> Hide/Show

===Displaying the value of a point===
Double click on the desired point; it will be highlighted and its value will be displayed in the upper right corner

=Functions=
==PlotSurface==
This function creates a plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
[[File:ia2514_fig6.png|400px|right|thumb|Figure 1. Plot generated by PlotSurface]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Example===
<pre>python PlotCube_mayavi.py PlotSurface test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 1.

==PlotIsoVdW==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid). The points within <code>iso</code>±<code>iso_range</code> in their corresponding colours and the others in grey.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) =
* <code>grey_surf</code> (boolean, default=False) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
[[File:ia2514_fig8.png|400px|right|thumb|Figure 2. Plot generated by PlotIsoVdW]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
* Iso slider

===Example===
<pre>python PlotCube_mayavi.py PlotIsoVdW test_emim_oac_esp.cube iso=1.1 iso_range=0.5</pre>
The resulting plot is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None)
* <code>iso_range</code> (float, default=0.01) =
[[File:ia2514_fig7.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* Iso slider

===Example===

<pre>python ReadCube_mayavi.py PlotIsosurface NH3CH2Cl_esp.cube colour='plasma' minmax=True iso=0.2</pre>
The resulting plot is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
[[File:ia2514_fig9.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
* a
* b
* c
* x0
* y0
* z0

===Example===
<pre>python PlotCube_mayavi.py PlotSlice test_emim_oac_esp.cube a=0.2 b=0.3 c=0.3</pre>
The resulting plot is shown in figure 4.

Mod:Hunt Research Group/Python scripts for cube files

2018-04-30T15:17:35Z

Ia2514:

The latest version of the Python scripts, along with a test cube file can be found [[:Media:OxanaAndriuc_23Apr_2018_Code.zip|here]].

The following scripts can be used to read, save, manipulate and visualise data from cube files:
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py ReadCube.py] - used to extract data from cube files and return it in convenient python formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py] - used to save data from cube files in convenient formats
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py CalculateCube.py] - used to manipulate data from cube files
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] - used to plot data from cube files (using [https://matplotlib.org Matplotlib])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] - used to plot data from cube files (using [http://docs.enthought.com/mayavi/mayavi/ Mayavi])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] - used to manipulate data not from cube files, but from files produced by the scripts above

If you want to save data from cube files
* for saving the values from the cube files, use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py SaveCube.py]
* for saving histogram data, use the function <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] with <code>save=True</code>
* for saving a short summary file of the minimum, maximum and lowest curvature points on the van der Waals surface, use <code>save=True</code> when running <code>PlotSurface</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]

If you want to plot surfaces, isosurfaces, slices
* use the functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py]. They are faster and better at 3D plotting than the equivalent functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]

If you want to generate static figures you can also consider using the 3D plotting functions from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py]. These are especially recommended when wanting to display atoms as they look better than their [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py] equivalents. However, keep in mind that Matplotlib sometimes fails at 3D rendering, which generates "incorrect" plots (i.e. elements that should be behind the rest of the plot appear at the front). Therefore, plots created using function from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] should be double-checked (by comparing them with plots from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py PlotCube_mayavi.py], by example).

If you want to plot histograms and KDEs
* use <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] to plot a histogram and/or KDE directly from cube files
* use <code>OverlapKDEs</code> and <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/AdditionalFunctions.py AdditionalFunctions.py] to plot histograms and KDEs from files written by <code>PlotHistogram</code> from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py PlotCube.py] when <code>save=True</code>

Mod:Hunt Research Group/SaveCube.py

2018-04-28T12:10:17Z

Ia2514:

<code>SaveCube.py</code> is a collection of functions that save the data from cube files in convenient formats.

=Requirements=
* Python
* [https://pandas.pydata.org pandas]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
The saving functions can be run from the terminal window by typing:
<pre>python SaveCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==SaveAll==
This function writes the x, y, z coordinates and the values from a cube file to a new file (4 columns).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>outfile</code> (string, default=None) = path for the output file (if None, the script used the input filename with the extension ".csv"
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* very slow if run for all the points in a cube file
* the script predicts the size of the file (which is also an indication of the running time) and it allows the user to:
# Proceed
# Reduce the number of points then proceed
# Abort
* if the user selects option number 2, they will be asked to input an integer number n so that only every nth value is saved to the file. Afterwards, the scripts prints the new predicted size and allows the user to once again select between options 1, 2 and 3.

===Example===
<pre>python SaveCube.py SaveAll test_emim_oac_esp.cube outfile='emim_oac_all.csv'</pre>

This example will raise the follow message:

<pre>Your file size will be 34MB. Options: 1. Proceed 2. Reduce the number of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to reduce the number of points (by typing in 2 then enter), a new message will be printed:

<pre>Please input an integer number n so that only every n value is saved to the file:</pre>

If the user inputs the number 100 (by typing 100 then enter), the new message will be:

<pre>Your file size will be 340KB. Options: 1. Proceed 2. Reduce the number of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to proceed (by typing in 1 then enter), the new emim_oac_all.csv file should be:

<pre> X coord/A Y coord/A Z coord/A Value/V
-6.342285 -6.155011 -3.804660 1.98280E-01
-6.342285 -6.016080 2.169381 2.57662E-01
-6.342285 -5.738218 0.224345 3.08147E-01
-6.342285 -5.460355 -1.720692 2.99211E-01
-6.342285 -5.182493 -3.665729 2.39004E-01
...</pre>

==SaveVdW==
This function writes the x, y, z coordinates and the values of all the points that lie on a surface defined by the van der Waals radii of the atoms to a new file (4 columns).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>outfile</code> (string, default=None) = path for the output file (if None, the script used the input filename with the extension ".csv"
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* the script predicts the size of the file (which is also an indication of the running time) and it allows the user to:
# Proceed
# Reduce the number of points then proceed
# Abort
* if the user selects option number 2, they will be asked to input an integer number n so that only every nth value is saved to the file. Afterwards, the scripts prints the new predicted size and allows the user to once again select between options 1, 2 and 3.

===Example===
<pre>python SaveCube.py SaveVdW test_emim_oac_esp.cube outfile='emim_oac_vdw_dens2.csv' density=2</pre>

This example will raise the follow message:

<pre>Your file size will be 18KB. Options: 1. Proceed 2. Reduce the number of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to proceed (by typing in 1 then enter), the new emim_oac_vdw_dens2.csv file should be:

<pre> X coord/A Y coord/A Z coord/A Value/V
-4.952973 -0.875626 0.085413 1.88899E+00
-4.952973 -0.875626 0.363276 1.98856E+00
-4.952973 -0.875626 0.641138 1.90018E+00
-4.952973 -0.597764 -0.192449 1.72317E+00
-4.952973 -0.597764 0.085413 2.00726E+00
...</pre>

Mod:Hunt Research Group/SaveCube.py

2018-04-28T12:06:43Z

Ia2514: /* Example */

<code>SaveCube.py</code> is a collection of functions that save the data from cube files in convenient formats.

=Requirements=
* Python
* [https://pandas.pydata.org pandas]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
The saving functions can be run from the terminal window by typing:
<pre>python SaveCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==SaveAll==
This function writes the x, y, z coordinates and the values from a cube file to a new file (4 columns).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>outfile</code> (string, default=None) = path for the output file (if None, the script used the input filename with the extension ".csv"
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* very slow if run for all the points in a cube file
* the script predicts the size of the file (which is also an indication of the running time) and it allows the user to:
# Proceed
# Reduce the density of points then proceed
# Abort
* if the user selects option number 2, they will be asked to input an integer number n so that only every nth value is saved to the file. Afterwards, the scripts prints the new predicted size and allows the user to once again select between options 1, 2 and 3.

===Example===
<pre>python SaveCube.py SaveAll test_emim_oac_esp.cube outfile='emim_oac_all.csv'</pre>

This example will raise the follow message:

<pre>Your file size will be 34MB. Options: 1. Proceed 2. Reduce the density of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to reduce the density of points (by typing in 2 then enter), a new message will be printed:

<pre>Please input an integer number n so that only every n value is saved to the file:</pre>

This density value is not equivalent to the <code>density</code> argument of the function. This density m reduces the total number of points by m (cf. the <code>density</code> parameter which for a value of n, reduces the number of data points by n3). If the user selects the new density of 100 (by typing 100 then enter), the new message will be:

<pre>Your file size will be 340KB. Options: 1. Proceed 2. Reduce the density of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to proceed (by typing in 1 then enter), the new emim_oac_all.csv file should be:

<pre> X coord/A Y coord/A Z coord/A Value/V
-6.342285 -6.155011 -3.804660 1.98280E-01
-6.342285 -6.016080 2.169381 2.57662E-01
-6.342285 -5.738218 0.224345 3.08147E-01
-6.342285 -5.460355 -1.720692 2.99211E-01
-6.342285 -5.182493 -3.665729 2.39004E-01
...</pre>

==SaveVdW==
This function writes the x, y, z coordinates and the values of all the points that lie on a surface defined by the van der Waals radii of the atoms to a new file (4 columns).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>outfile</code> (string, default=None) = path for the output file (if None, the script used the input filename with the extension ".csv"
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* the script predicts the size of the file (which is also an indication of the running time) and it allows the user to:
# Proceed
# Reduce the density of points then proceed
# Abort
* if the user selects option number 2, they will be asked to input an integer number n so that only every nth value is saved to the file. Afterwards, the scripts prints the new predicted size and allows the user to once again select between options 1, 2 and 3.

===Example===
<pre>python SaveCube.py SaveVdW test_emim_oac_esp.cube outfile='emim_oac_vdw_dens2.csv' density=2</pre>

This example will raise the follow message:

<pre>Your file size will be 18KB. Options: 1. Proceed 2. Reduce the density of points then proceed 3. Abort. Pick an option [1/2/3]:</pre>

If the user chooses to proceed (by typing in 1 then enter), the new emim_oac_vdw_dens2.csv file should be:

<pre> X coord/A Y coord/A Z coord/A Value/V
-4.952973 -0.875626 0.085413 1.88899E+00
-4.952973 -0.875626 0.363276 1.98856E+00
-4.952973 -0.875626 0.641138 1.90018E+00
-4.952973 -0.597764 -0.192449 1.72317E+00
-4.952973 -0.597764 0.085413 2.00726E+00
...</pre>

Mod:Hunt Research Group/ReadCube.py

2018-04-27T16:46:59Z

Ia2514: /* Axes */

<code>ReadCube.py</code> is a collection of functions that extract data from cube files and return it in convenient python formats. These are the main functions used by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>], [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py <code>PlotCube_mayavi.py</code>], [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py <code>SaveCube.py</code>] and [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>].

=Requirements=
* Python

An easy way to obtain Python is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
If you want to use the functions in <code>ReadCube.py</code> to extract data from cube files in Python, you will need to write a Python script:
<pre>
import ReadCube as rc
var1 = rc.function_name(arg1=val1, arg2=val2,...)
<do something with var1: print it, save it to file, etc.>
</pre>

The Python script can be written and ran in different ways:
* as a new .py file using Spyder (Spyder <math>\rightarrow</math> File <math>\rightarrow</math> New file... <math>\rightarrow</math> [write the file] <math>\rightarrow</math> Save As... [make sure you save the file in the same directory as <code>ReadCube.py</code>] <math>\rightarrow</math> Run <math>\rightarrow</math> Run [the file will be run in the iPython console]
* in the IPython console in Spyder: write the Python commands directly in the console, but make sure that the current working directory is the one containing <code>ReadCube.py</code>
* in the terminal window: type <code>ipython</code>, then write the Python commands directly in the terminal, but make sure that the current working directory is the one containing <code>ReadCube.py</code>

===Example===
<pre>
import ReadCube as rc
at = rc.Atoms(fpath='test_emim_oac_esp.cube')
print([i[0] for i in at])
</pre>
This example prints the atomic numbers of all the constituent atoms:
<pre>
[7, 6, 1, 1, 1, 6, 1, 7, 6, 1, 1, 6, 1, 1, 1, 6, 6, 1, 1, 6, 8, 8, 6, 1, 1, 1]
</pre>

=Functions=
==ExtractData==
This function extracts all the data from the cube file.

===Required parameters===
* <code>fpath</code> (string) = path for a cube file

===Optional parameters===
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Returns===
a list of: the number of atoms, a list of the coordinates of the origin, the number of values recorded at each point, the number of voxels along x axis, a list of the coordinates of the increment vector for the x axis, the number of voxels along y axis, a list of the coordinates of the increment vector for the y axis, the number of voxels along z axis, a list of the coordinates of the increment vector for the z axis, a list of lists containing the atomic number, the nuclear charge and coordinates for each atom, a list of MO indices, a 3D array of all the values in the cube file, a list of all the values in the cube file, value units (in order)

==Atoms==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>value_type</code> (string, default='esp') = value type
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom

==Axes==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>n_x</code> (integer, default=None) = number of voxels along x axis
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>n_y</code> (integer, default=None) = number of voxels along y axis
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>n_z</code> (integer, default=None) = number of voxels along z axis
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)

===Returns===
a list of three lists representing the x, y and z coordinates, respectively of the grid points

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>origin, n_x, x_vector, n_y, y_vector, n_z, z_vector</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==ValuesAsMatrix==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a 3D array of all the values in the cube file

==ValuesAsList==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a list of all the values in the cube file (in the order in which they appear)

==ValuesAsDictionary==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)

===Returns===
a list of an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value and an ordered dictionary of each grid point (represented through a tuple of its indices) and its corresponding value

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>vals, axes_list, origin</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==Minimum==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list the coordinates of all the grid points that have the minimum value

===Observations===

* called with either <code>fpath, au, density, value_type, units</code> or <code>gridpts, vals</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==Maximum==

* <code>fpath</code> (string, default=None) = path for a cube file
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list the coordinates of all the grid points that have the maximum value

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>gridpts, vals</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==GetVdWPoints==
This function returns all the points that are close to the surface defined in terms of the Van der Waals radii of the constituent atoms.

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>atoms_list</code> (list, default=None) = a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Atoms <code>Atoms</code>])
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>cat</code> (boolean, default=False) = if True, it only selects the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside the code)
* <code>an</code> (boolean, default=False) = if True, it only selects the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside the code; the atoms belonging to the anion are the remaining ones)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list of three lists: the first one contains the x, y, z coordinates and the value of each point on the VdW surface, the second one contains the indices and the value of each point on the VdW surface and the third one contains the coordinates and values of all the points that are on or inside the VdW surface

===Observations===
* called with either <code>fpath, au, density, value_type, units, factor</code> or <code>axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, origin, factor</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).
* the points that reside on the VdW surface are chosen to be within plus/minus a fractional distance of the surface defined by the Van der Waals radii of the constituent atoms (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid)
* if you want to only select certain points from the van der Waals surface, you can change this manually inside the code; this also applies for only selecting points which belong to either the cation or the anion (for which there are the parameters <code>cat</code> and <code>an</code>, respectively)

Mod:Hunt Research Group/ReadCube.py

2018-04-27T16:46:09Z

Ia2514: /* Axes */

<code>ReadCube.py</code> is a collection of functions that extract data from cube files and return it in convenient python formats. These are the main functions used by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube.py <code>PlotCube.py</code>], [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/PlotCube_mayavi.py <code>PlotCube_mayavi.py</code>], [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/SaveCube.py <code>SaveCube.py</code>] and [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>].

=Requirements=
* Python

An easy way to obtain Python is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
If you want to use the functions in <code>ReadCube.py</code> to extract data from cube files in Python, you will need to write a Python script:
<pre>
import ReadCube as rc
var1 = rc.function_name(arg1=val1, arg2=val2,...)
<do something with var1: print it, save it to file, etc.>
</pre>

The Python script can be written and ran in different ways:
* as a new .py file using Spyder (Spyder <math>\rightarrow</math> File <math>\rightarrow</math> New file... <math>\rightarrow</math> [write the file] <math>\rightarrow</math> Save As... [make sure you save the file in the same directory as <code>ReadCube.py</code>] <math>\rightarrow</math> Run <math>\rightarrow</math> Run [the file will be run in the iPython console]
* in the IPython console in Spyder: write the Python commands directly in the console, but make sure that the current working directory is the one containing <code>ReadCube.py</code>
* in the terminal window: type <code>ipython</code>, then write the Python commands directly in the terminal, but make sure that the current working directory is the one containing <code>ReadCube.py</code>

===Example===
<pre>
import ReadCube as rc
at = rc.Atoms(fpath='test_emim_oac_esp.cube')
print([i[0] for i in at])
</pre>
This example prints the atomic numbers of all the constituent atoms:
<pre>
[7, 6, 1, 1, 1, 6, 1, 7, 6, 1, 1, 6, 1, 1, 1, 6, 6, 1, 1, 6, 8, 8, 6, 1, 1, 1]
</pre>

=Functions=
==ExtractData==
This function extracts all the data from the cube file.

===Required parameters===
* <code>fpath</code> (string) = path for a cube file

===Optional parameters===
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Returns===
a list of: the number of atoms, a list of the coordinates of the origin, the number of values recorded at each point, the number of voxels along x axis, a list of the coordinates of the increment vector for the x axis, the number of voxels along y axis, a list of the coordinates of the increment vector for the y axis, the number of voxels along z axis, a list of the coordinates of the increment vector for the z axis, a list of lists containing the atomic number, the nuclear charge and coordinates for each atom, a list of MO indices, a 3D array of all the values in the cube file, a list of all the values in the cube file, value units (in order)

==Atoms==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>value_type</code> (string, default='esp') = value type
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom

==Axes==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>n_x</code> (integer, default=None) = number of voxels along x axis
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>n_y</code> (integer, default=None) = number of voxels along y axis
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>n_z</code> (integer, default=None) = number of voxels along z axis
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)

===Returns===
a list of three lists representing the x, y and z coordinates, respectively of all the grid points

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>origin, n_x, x_vector, n_y, y_vector, n_z, z_vector</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==ValuesAsMatrix==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a 3D array of all the values in the cube file

==ValuesAsList==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]

===Returns===
a list of all the values in the cube file (in the order in which they appear)

==ValuesAsDictionary==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)

===Returns===
a list of an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value and an ordered dictionary of each grid point (represented through a tuple of its indices) and its corresponding value

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>vals, axes_list, origin</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==Minimum==

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list the coordinates of all the grid points that have the minimum value

===Observations===

* called with either <code>fpath, au, density, value_type, units</code> or <code>gridpts, vals</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==Maximum==

* <code>fpath</code> (string, default=None) = path for a cube file
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>vals</code> (list, default=None) = a list of all the values in the cube file
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list the coordinates of all the grid points that have the maximum value

===Observations===
* called with either <code>fpath, au, density, value_type, units</code> or <code>gridpts, vals</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).

==GetVdWPoints==
This function returns all the points that are close to the surface defined in terms of the Van der Waals radii of the constituent atoms.

===Parameters===
* <code>fpath</code> (string, default=None) = path for a cube file
* <code>axes_list</code> (list, default=None) = a list of three lists representing the x, y and z coordinates, respectively of all the sampling points (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>])
* <code>gridpts</code> (dictionary, default=None) = an ordered dictionary of each grid point (represented through a tuple of its coordinates) and its corresponding value (the first element in the list generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>])
* <code>atoms_list</code> (list, default=None) = a list of a number of natoms lists, each list component containing the atomic number, nuclear charge and coordinates of each atom (as generated by [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Atoms <code>Atoms</code>])
* <code>x_vector</code> (list, default=None) = increment vector in the x direction
* <code>y_vector</code> (list, default=None) = increment vector in the y direction
* <code>z_vector</code> (list, default=None) = increment vector in the z direction
* <code>origin</code> (list, default=None) = a list of the x, y and z coordinates of the origin
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>cat</code> (boolean, default=False) = if True, it only selects the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside the code)
* <code>an</code> (boolean, default=False) = if True, it only selects the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside the code; the atoms belonging to the anion are the remaining ones)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (if <code>fpath</code> is specified)
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (if <code>fpath</code> is specified)

===Returns===
a list of three lists: the first one contains the x, y, z coordinates and the value of each point on the VdW surface, the second one contains the indices and the value of each point on the VdW surface and the third one contains the coordinates and values of all the points that are on or inside the VdW surface

===Observations===
* called with either <code>fpath, au, density, value_type, units, factor</code> or <code>axes_list, gridpts, atoms_list, x_vector, y_vector, z_vector, origin, factor</code>
* if specified, <code>fpath</code> takes priority over the other arguments and [[https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>]] is called (i.e. the script reads and goes through the whole cube file).
* the points that reside on the VdW surface are chosen to be within plus/minus a fractional distance of the surface defined by the Van der Waals radii of the constituent atoms (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid)
* if you want to only select certain points from the van der Waals surface, you can change this manually inside the code; this also applies for only selecting points which belong to either the cation or the anion (for which there are the parameters <code>cat</code> and <code>an</code>, respectively)

Mod:Hunt Research Group/PlotCube.py

2018-04-26T18:59:15Z

Ia2514: /* PlotHistogram */

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer/None/string, default=30) = the number of bins in the histogram (see [https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.histogram.html here] for details)
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values
* <code>cat</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>])
* <code>an</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>]; the atoms belonging to the anion are the remaining ones)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube.py

2018-04-26T18:56:21Z

Ia2514: /* PlotHistogram */

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer, default=30) = the number of bins in the histogram
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values
* <code>cat</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the cation (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>])
* <code>an</code> (boolean, default=False) = if True, it only plots the histogram and/or KDE for the points that correspond to the anion (the condition for which atoms belong to the cation has to be changed manually inside [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>]; the atoms belonging to the anion are the remaining ones)

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube.py

2018-04-26T18:53:00Z

Ia2514: /* PlotSlice */

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>a</code> (float, default=0) = the x component of the normal vector defining the plane
* <code>b</code> (float, default=0) = the y component of the normal vector defining the plane
* <code>c</code> (float, default=1) = the z component of the normal vector defining the plane
* <code>x0</code> (float, default=None) = the x coordinate of the origin for the normal vector defining the plane
* <code>y0</code> (float, default=None) = the y coordinate of the origin for the normal vector defining the plane
* <code>z0</code> (float, default=None) = the z coordinate of the origin for the normal vector defining the plane
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer, default=None) = the number of bins in the histogram
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube.py

2018-04-26T18:49:46Z

Ia2514: /* PlotIsosurface */

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minima and maxima
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) = how large the plot is displayed with respect to the default size
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None) = the value of the points to be plotted
* <code>iso_range</code> (float, default=0.01) = the value range to consider when selecting the points (i.e. <code>iso</code>±0.01 by default)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer, default=None) = the number of bins in the histogram
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube.py

2018-04-26T18:46:59Z

Ia2514: /* Optional arguments */

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) = the value range to consider for the minimum and maximum
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None)
* <code>iso_range</code> (float, default=0.01) =
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer, default=None) = the number of bins in the histogram
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube.py

2018-04-26T18:45:58Z

Ia2514: /* PlotSurface */

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.05) = the value range to consider for the minima and maxima (i.e. ±0.05 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) = if True, it saves a .txt file with a summary of the results (minimum, maximum and lowest curvature)
* <code>grey_surf</code> (boolean, default=False) = if True, it plots a grey surface just below the van der Waals surface
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None)
* <code>iso_range</code> (float, default=0.01) =
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer, default=None) = the number of bins in the histogram
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.

Mod:Hunt Research Group/PlotCube.py

2018-04-26T18:43:52Z

Ia2514: /* Optional arguments */

<code>PlotCube.py</code> is a collection of functions that plot data from cube files.

=Requirements=
* Python
* Matplotlib
* NumPy
* scipy
* [https://gist.github.com/jdiscar/9144764 gistfile1]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>]
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>]

An easy way to obtain Python with the required modules is by installing [https://anaconda.org Anaconda].

Anaconda comes with Spyder, which is a Python editor that you can use to write and run Python codes (Applications <math>\rightarrow</math> Anaconda Navigator <math>\rightarrow</math> spyder <math>\rightarrow</math> Launch)

=Instructions=
==Running the code==
The plotting functions can be run from the terminal window by typing:

<pre>python ReadCube.py function_name cube_file_path arg1=val1 arg2=val2...</pre>

=Functions=
==PlotMesh==
This function creates an interactive plot of the cube file values.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>xlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the x values (by default all the x values from the cube file are plotted)
* <code>ylim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the y values (by default all the y values from the cube file are plotted)
* <code>zlim</code> (list,default=[None, None]) = a list of two values to be used as the lower and upper limit for the z values (by default all the z values from the cube file are plotted)
* <code>alpha</code> (float, default=0.1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=0.05) = marker size
* <code>lower_cutoff</code> (float, default=None) = the lower limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>upper_cutoff</code> (float, default=None) = the upper limit of the values to be plotted (by default all the values from the cube file are plotted)
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) = the value range to consider for the minima and maxima (i.e. ±0.01 by default)
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:Fig1.png|400px|right|thumb|Figure 1. Plot generated by PlotMesh]]
* lower cutoff value
* upper cutoff value
* alpha
* size

===Buttons===

* axes: on/off
* minima and maxima: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)

===Observations===
* SLOW
* ONLY WORKS FOR ORTHONORMAL GRIDS
* If you click on a point, it will be highlighted and its value will be displayed in the upper right corner.

===Example===
<pre>python PlotCube.py PlotMesh test_emim_oac_esp.cube colour='plasma' axes=True</pre>

Plot shown in figure 1.

==PlotSurface==
This function creates an interactive plot of all the points which reside within +/- a fractional distance from the surface defined in terms of the Van der Waals radii of the atoms in the molecule (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=1) = marker size
* <code>axes</code> (boolean, default=False) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0.01) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=True) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>save</code> (boolean, default=False) =
* <code>grey_surf</code> (boolean, default=False) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py#VdWLaplacian <code> VdWLaplacian </code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/CalculateCube.py <code>CalculateCube.py</code>])

===Sliders===
[[File:ia2514_fig2.png|400px|right|thumb|Figure 2. Plot generated by PlotSurface]]
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSurface test_emim_oac_esp.cube bkg=[0.2,0.2,0.3] </pre>
The resulting plot, shown after changing the alpha and zoom values using the slider, is shown in figure 2.

==PlotIsosurface==
This function creates an interactive plot of all the points which are within a specified value range from a given value.

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=True) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>iso</code> (float, default=None)
* <code>iso_range</code> (float, default=0.01) =
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig3.png|400px|right|thumb|Figure 3. Plot generated by PlotIsosurface]]
* value
* azimuth
* elevation
* alpha
* size
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotIsosurface test_emim_oac_esp.cube iso=0.01 iso_range=0.02</pre>
The resulting plot after rotation is shown in figure 3.

==PlotSlice==
This function generates an interactive plot of all the points which reside within +/- a fractional distance from a plane defined in terms of a normal vector and an origin (the fractional distance represents 30% of the distance between two diagonally adjacent points in the grid).

===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>alpha</code> (float, default=1) = transparency value (between 0 and 1)
* <code>size</code> (float, default=4) = marker size
* <code>axes</code> (boolean, default=True) = if True, show axes; if False, hide axes
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>bkg</code> (tuple/list/string, default=(1, 1, 1)) = background colour (RGB tuple/list or name - each value between 0 and 1, white by default)
* <code>minmax</code> (boolean, default=False) = if True, show minima and maxima; if False, hide minima and maxima
* <code>minmax_range</code> (float, default=0) =
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
* <code>atoms</code> (boolean, default=False) = if True, show atoms; if False, hide atoms
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>curvature</code> (boolean, default=False) = if True, plots curvature points (either based on cv_lim if given, or cv_pts)
* <code>cv_lim</code> (float, default=None) = the upper limit of the curvature for the low curvature points to be plotted (it overrides cv_pts if given)
* <code>cv_pts</code> (integer, default=5) = the number of low curvature points to be plotted (the points will be chosen in increasing order of their absolute curvature
* <code>zoom</code> (float, default=1) =
* <code>a</code> (float, default=0) =
* <code>b</code> (float, default=0) =
* <code>c</code> (float, default=1) =
* <code>x0</code> (float, default=None) =
* <code>y0</code> (float, default=None) =
* <code>z0</code> (float, default=None) =
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>contour</code> (boolean, default=True) = if True, show van der Waals contour; if False, hide van der Waals contour
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Sliders===
[[File:ia2514_fig4.png|400px|right|thumb|Figure 4. Plot generated by PlotSlice]]
* a
* b
* c
* x0
* y0
* z0
* zoom

===Buttons===
* axes: on/off
* minima and maxima: on/off
* atoms: on/off
* colour: 'rainbow', 'bwr' and the value passed for the <code>colour</code> parameter (if different from 'rainbow' and 'bwr')
* background colour: 'white', 'black' and the value passed for the <code>bkg</code> parameter (if different from white and black)
* curvature: on/off

===Example===
<pre>python PlotCube.py PlotSlice test_emim_oac_esp.cube colour='plasma'</pre>
The resulting plot is shown in figure 4.

==PlotHistogram==
===Required arguments===
* <code>fpath</code> (string) = path for a cube file

===Optional arguments===
* <code>factor</code> (float, default=1) = factor by which to multiply the VdW radii
* <code>bins</code> (integer, default=None) = the number of bins in the histogram
* <code>hist</code> (boolean, default=True) = if True, it plots the histogram; if False, it does not plot the histogram (only the KDE)
* <code>kde</code> (boolean, default=True) = if True, it plots a gaussian kernel density estimate (KDE = a way to estimate the probability density function of a variable); if False, it does not plot the KDE
* <code>norm_freq</code> (boolean, default=False) = if True, it plots a histogram with normalised frequency (without KDE, because the KDE has a normalised area, not normalised bin heights)
* <code>norm_hist</code> (boolean, default=True) = if True, it normalises the histogram (i.e. integral=1) - this happens by default for plots including KDE
* <code>au</code> (boolean, default=False) = if True, use atomic units (i.e. bohr for coordinates); if False, use Angstroms for coordinates and <code>units</code> for values
* <code>density</code> (integer, default=1) = an integer number n which indicates that the number of points stored along each axis is reduced by the density value n (therefore the total number of points is reduced by n3)
* <code>value_type</code> (string, default='esp') = can be ‘esp’/’potential’ or ‘dens’/’density’ (or any uppercase version of the aforementioned); used in conjunction with the keywords <code>au</code> and <code>units</code> in order to convert the values to the appropriate units
* <code>units</code> (string, default=None) = the units to be used for the value; currently supports ‘V’ for ESP and ‘A’/‘angstrom’, ’nm’, ’pm’, ’m’ for density (or any lowercase/uppercase version of these). In the case of the density, the actual units are the specified units ^(-3). The keywords <code>value_type</code> and <code>au</code> override <code>units</code>. If <code>au</code> is True, the values will be in atomic units regardless of the value passed for <code>units</code>. If <code>value_type</code> is ‘dens’, the values will be read as density values even if the <code>units</code> argument has a valid ESP value (such as ‘V’). The default unit for ESP is V and for density 1/Å3.
* <code>colour</code> (string, default='rainbow') = colour scheme ('rainbow' by default, change it to 'bwr' for blue-white-red) - full list [https://matplotlib.org/users/colormaps.html here]
* <code>cb_lim</code> (list, default=None) = limits for the colour bar (list of two floats; if not specified, the limits will be the min and max of the values; if the limits do not cover the whole range of values, a warning is printed)
[[File:ia2514_fig5.png|400px|right|thumb|Figure 5. Plot generated by PlotHistogram]]
* <code>xlim</code> (list, default=None) = x axis limits
* <code>ylim</code> (list, default=None) = y axis limits
* <code>save</code> (boolean, default=True) = if True: if <code>hist</code> is also True, a file <original_file_name>_hist.out is created, containing the bin edges values and the frequency for each bin as shown in the histogram; if <code>kde</code> is also True, a file <original_file_name>_kde.out is created, containing the range of values used for plotting the KDE and the corresponding KDE value. The file ends with two separate sections: peak values and minimum values

===Calls===
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ExtractData <code>ExtractData</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#Axes <code>Axes</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#ValuesAsDictionary <code>ValuesAsDictionary</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])
* [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py#GetVdWPoints <code>GetVdWPoints</code>] (from [https://wiki.ch.ic.ac.uk/wiki/index.php?title=Mod:Hunt_Research_Group/ReadCube.py <code>ReadCube.py</code>])

===Observations===
* if you only want to specify one limit for either of the axis, use None for the other (e.g. xlim=[None,3.5])

===Example===
<pre>python PlotCube.py PlotHistogram test_emim_oac_esp.cube</pre>
The resulting plot is shown in figure 5.