plot

The plot module has all the functions related to plotting variables.

# Example:
import analysator as pt
pt.pt.
#press [tab] -> get the functions

class analysator.plot.Number

All numbers inherit from this class.

If you just want to check if an argument x is a number, without caring what kind, use isinstance(x, Number).

analysator.plot.get_scaled_units(variable_info, vscale=None, env='EarthSpace', manualDict=None)

Return scaling metadata

Parameters:

• variable_info – VariableInfo object used for getting the units

• env – A string to choose the scaling dictionary [default: EarthSpace]

• manualDict – a dictionary of {units : {scalingparams}}; used to update the included dictionary

• vscale – float, factor to scale the variable with

Returns:

(norming factor, scaledUnits, scaledLatexUnits)

analysator.plot.get_scaled_var(variable_info, vscale=None, data=None, env='EarthSpace', manualDict=None)

Automatically scales the variableinfo data and adjusts the units correspondingly with the default dictionaries.

Parameters:

• variable_info – VariableInfo object used for getting the units

• data – in case you wish to provide new data array (why, though?)

• env – A string to choose the scaling dictionary [default: EarthSpace]

• manualDict – a dictionary of {units : {scalingparams}}; used to update the included dictionary

Returns:

variable_info, with scaled units with pre-formatted units included in the varinfo.

analysator.plot.plot_colormap(filename=None, vlsvobj=None, filedir=None, step=None, outputdir=None, outputfile=None, nooverwrite=False, var=None, op=None, operator=None, title=None, cbtitle=None, draw=None, usesci=True, symlog=None, diff=None, boxm=None, boxre=None, colormap=None, run=None, nocb=False, internalcb=False, wmark=False, wmarkb=False, axisunit=None, thick=1.0, scale=1.0, tickinterval=0, noborder=False, noxlabels=False, noylabels=False, vmin=None, vmax=None, lin=None, external=None, expression=None, vscale=1.0, absolute=False, symmetric=False, pass_vars=None, pass_times=None, pass_full=False, fluxfile=None, fluxdir=None, flux_levels=None, fluxthick=1.0, fluxlines=1, fluxlinecolor='k', fsaved=None, nomask=False, Earth=None, highres=None, vectors=None, vectordensity=100, vectorcolormap='gray', vectorsize=1.0, streamlines=None, streamlinedensity=1, streamlinecolor='white', streamlinethick=1.0, axes=None, cbaxes=None, cb_horizontal=False, useimshow=False, imshowinterp='none', flipxaxis=False)

Plots a coloured plot with axes and a colour bar.

Parameters:

• filename – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final part will be used as a prefix for the files.

• outputfile – Singular output file name

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• var – variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, E, B, v, V or others. Accepts any variable known by analysator. Per-population variables are simply given as “proton/rho” etc

• operator – Operator to apply to variable: None, x, y, or z. Vector variables return either the queried component, or otherwise the magnitude.

• op – duplicate of operator

• boxm – zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box)

• boxre – zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box)

• colormap – colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, magma, parula, nipy_spectral, RdBu, bwr

• run – run identifier, used for constructing output filename

• title – string to use as plot title instead of time. Special case: Set to “msec” to plot time with millisecond accuracy or “musec” for microsecond accuracy. “sec” is integer second accuracy.

• cbtitle – string to use as colorbar title instead of map name

• axisunit – Plot axes using 10^{axisunit} m (default: Earth radius R_E)

• tickinterval – Interval at which to have ticks on axes (not colorbar)

• usesci – Use scientific notation for colorbar ticks? (default: True)

• vmin,vmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot (non-zero rho regions only) are used.

• symmetric – Set the absolute value of vmin and vmax to the greater of the two

• lin – Flag for using linear colour scaling instead of log. If an integer, defines number of colorbar ticks.

• symlog – Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. Allows symmetric quasi-logarithmic plots of e.g. transverse field components. A given of 0 or True translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can result in the innermost tick marks overlapping. In this case, using a larger value for symlog is suggested.

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• wmarkb – As for wmark, but uses an all-black Vlasiator logo.

• Earth – If set, draws an earth at (0,0)

• highres – Creates the image in high resolution, scaled up by this value (suitable for print).

• draw – Set to anything but None or False in order to draw image on-screen instead of saving to file (requires x-windowing)

• noborder – Plot figure edge-to-edge without borders (default off)

• noxlabels – Suppress x-axis labels and title

• noylabels – Suppress y-axis labels and title

• scale – Scale text size (default=1.0)

• thick – line and axis thickness, default=1.0

• nocb – Set to suppress drawing of colourbar

• internalcb – Set to draw colorbar inside plot instead of outside. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• external – Optional function to use for external plotting of e.g. contours. The function receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps If the function accepts a fifth variable, if set to true, it is expected to return a list of required variables for constructing the pass_maps dictionary. See note under expression about the dictionaries of arrays.

• expression – Optional function which calculates a custom expression to plot. The function receives the same dictionary of numpy arrays as external, as an argument pass_maps, the contents of which are maps of variables. Each is either of size [ysize,xsize] or for multi-dimensional variables (vectors, tensors) it’s [ysize,xsize,dim]. If the function accepts a second variable, if set to true, it is expected to return a list of required variables for pass_maps. Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions on, see the plot_helpers.py file.

• diff – Instead of a regular plot, plot the difference between the selected plot type for the regular source file and the file given by this keyword. This overides external and expression keywords, as well as related pass_vars, pass_times, and pass_full.

• vscale – Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 or from tesla to nanotesla. Guesses correct units for colourbar for some known variables. Set to None to search for a default scaling settings.

• absolute – Plot the absolute of the evaluated variable

• pass_vars – Optional list of map names to pass to the external/expression functions as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or for multi-dimensional variables (vectors, tensors) it’s [ysize,xsize,dim].

• pass_times – Integer, how many timesteps in each direction should be passed to external/expression functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If pass_times has two values, the first is the extent before, the second after. (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps for a total of four timesteps) This causes pass_vars to become a list of timesteps, with each timestep containing a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is added as ‘dstep’ which gives the timestep offset from the master frame. Does not work if working from a vlsv-object.

• pass_full – Set to anything but None in order to pass the full arrays instead of a zoomed-in section

• fluxfile – Filename to plot fluxfunction from

• flux_levels – A list of flux function values to plot as the contours (default: None, a set of constant intervals: np.linspace(-10,10,fluxlines*60))

• fluxdir – Directory in which fluxfunction files can be found

• fluxthick – Scale fluxfunction line thickness

• fluxlines – Relative density of fluxfunction contours

• fluxlinecolor – Set flux line color (default black)

• fsaved – Overplot locations of fSaved. If keyword is set to a string, that will be the colour used.

• nomask – Do not mask plotting based on proton density

• vectors – Set to a vector variable to overplot (unit length vectors, color displays variable magnitude)

• vectordensity – Aim for how many vectors to show in plot window (default 100)

• vectorcolormap – Colormap to use for overplotted vectors (default: gray)

• vectorsize – Scaling of vector sizes

• streamlines – Set to a vector variable to overplot as streamlines

• streamlinedensity – Set streamline density (default 1)

• streamlinecolor – Set streamline color (default white)

• streamlinethick – Set streamline thickness

• axes – Provide the routine a set of axes to draw within instead of generating a new image. It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar to be automatically added next to the panel (but this may affect the overall layout) Note that the aspect ratio of the colormap is made equal in any case, hence the axes proportions may change if the box and axes size are not designed to match by the user

• cbaxes – Provide the routine a set of axes for the colourbar.

• cb_horizontal – Set to draw the colorbar horizontally instead of vertically (default: False) requires cbaxes to be set.

• useimshow – Use imshow for raster background instead (default: False)

• imshowinterp – Use this matplotlib interpolation for imshow (default: ‘none’)

• flipxaxis – Invert output plot x/horizontal axis so that e.g. the Sun is on the left (default: False)

Returns:

Outputs an image to a file or to the screen.

# Example usage:
plot_colormap(filename=fileLocation, var="MA", run="BCQ",
            colormap='nipy_spectral',step=j, outputdir=outputLocation,
            lin=True, wmark=1, vmin=2.7, vmax=10, 
            external=cavitoncontours, pass_vars=['rho','B','beta'])
# Where cavitoncontours is an external function which receives the arguments
#  ax, XmeshXY,YmeshXY, pass_maps
# where pass_maps is a dictionary of maps for the requested variables.

# example (simple) use of expressions:
def exprMA_cust(exprmaps, requestvariables=False):
    if requestvariables==True:
    return ['va']
    custombulkspeed=750000. # m/s
    va = exprmaps['va'][:,:]
    MA = custombulkspeed/va
    return MA
plot_colormap(filename=fileLocation, vmin=1 vmax=40, expression=exprMA_cust,lin=True)

analysator.plot.plot_colormap3dslice(filename=None, vlsvobj=None, filedir=None, step=None, run=None, outputdir=None, outputfile=None, nooverwrite=False, var=None, op=None, operator=None, title=None, cbtitle=None, draw=None, usesci=True, symlog=None, boxm=None, boxre=None, colormap=None, nocb=False, internalcb=False, wmark=False, wmarkb=False, axisunit=None, thick=1.0, scale=1.0, tickinterval=0, noborder=False, noxlabels=False, noylabels=False, vmin=None, vmax=None, lin=None, external=None, expression=None, limitedsize=False, diff=None, vscale=1.0, absolute=False, symmetric=False, pass_vars=None, pass_times=None, pass_full=False, fsaved=None, fsavedlinewidth=0.5, fsavedcolour='black', fsavedlinestyle='solid', fluxrope=0, fluxropelinewidth=0.5, fluxropecolour=None, fluxropelinestyle=None, amr=None, amrlinewidths=0.5, amrcolours='black', amrlinestyles='solid', nomask=None, Earth=None, highres=None, vectors=None, vectordensity=100, vectorcolormap='gray', vectorsize=1.0, streamlines=None, streamlinedensity=1, streamlinecolor='white', streamlinethick=1.0, axes=None, cbaxes=None, cb_horizontal=False, normal='y', cutpoint=0.0, cutpointre=None, flipxaxis=False, useimshow=False, imshowinterp='none')

Plots a coloured plot with axes and a colour bar, slicing through a 3D domain. Currently only supports axis- aligned slices.

Parameters:

• filename – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• run – run identifier, used for constructing output filename

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final part will be used as a prefix for the files.

• outputfile – Singular output file name

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• var – variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, E, B, v, V or others. Accepts any variable known by analysator. Per-population variables are simply given as “proton/rho” etc

• operator – Operator to apply to variable: None, x, y, or z. Vector variables return either the queried component, or otherwise the magnitude.

• op – duplicate of operator

• boxm – zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box)

• boxre – zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box)

• colormap – colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, magma, parula, nipy_spectral, RdBu, bwr

• title – string to use as plot title instead of time. Special case: Set to “msec” to plot time with millisecond accuracy or “musec” for microsecond accuracy. “sec” is integer second accuracy.

• cbtitle – string to use as colorbar title instead of map name

• axisunit – Plot axes using 10^{axisunit} m (default: Earth radius R_E)

• tickinterval – Interval at which to have ticks on axes (not colorbar)

• usesci – Use scientific notation for colorbar ticks? (default: True)

• vmin,vmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot (non-zero rho regions only) are used.

• symmetric – Set the absolute value of vmin and vmax to the greater of the two

• lin – Flag for using linear colour scaling instead of log

• symlog – Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. Allows symmetric quasi-logarithmic plots of e.g. transverse field components. A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can result in the innermost tick marks overlapping. In this case, using a larger value for symlog is suggested.

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• wmarkb – As for wmark, but uses an all-black Vlasiator logo.

• Earth – If set, draws an earth at (0,0)

• highres – Creates the image in high resolution, scaled up by this value (suitable for print).

• draw – Set to nonzero in order to draw image on-screen instead of saving to file (requires x-windowing)

• noborder – Plot figure edge-to-edge without borders (default off)

• noxlabels – Suppress x-axis labels and title

• noylabels – Suppress y-axis labels and title

• scale – Scale text size (default=1.0)

• thick – line and axis thickness, default=1.0

• nocb – Set to suppress drawing of colourbar

• internalcb – Set to draw colorbar inside plot instead of outside. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• external – Optional function to use for external plotting of e.g. contours. The function receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps If the function accepts a fifth variable, if set to true, it is expected to return a list of required variables for constructing the pass_maps dictionary. See note under expression about the dictionaries of arrays.

• expression – Optional function which calculates a custom expression to plot. The function receives the same dictionary of numpy arrays as external, as an argument pass_maps, the contents of which are maps of variables. Each is either of size [ysize,xsize] or for multi-dimensional variables (vectors, tensors) it’s [ysize,xsize,dim]. If the function accepts a second variable, if set to true, it is expected to return a list of required variables for pass_maps. Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions on, see the plot_helpers.py file.

• limitedsize – Calculates the requested variable for only the plotted region. Slower for regular variables, faster for computationally heavy variables.

• vscale – Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 or from tesla to nanotesla. Guesses correct units for colourbar for some known variables. Set to None to seek for a default scaling.

• absolute – Plot the absolute of the evaluated variable

• pass_vars – Optional list of map names to pass to the external/expression functions as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or for multi-dimensional variables (vectors, tensors) it’s [ysize,xsize,dim].

• pass_times – Integer, how many timesteps in each direction should be passed to external/expression functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If pass_times has two values, the first is the extent before, the second after. (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps for a total of four timesteps) This causes pass_vars to become a list of timesteps, with each timestep containing a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is added as ‘dstep’ which gives the timestep offset from the master frame. Does not work if working from a vlsv-object.

• pass_full – Set to anything but None in order to pass the full arrays instead of a zoomed-in section

• diff – Instead of a regular plot, plot the difference between the selected plot type for the regular source file and the file given by this keyword. This overides external and expression keywords, as well as related pass_vars, pass_times, and pass_full.

• fsaved – Overplot locations of fSaved. If keyword is set to a string, that will be the colour used.

• fsavedlinewidth – Line width for fSaved markers, default 0.5.

• fsavedlinestyle – Line style of fSaved markers, default “solid”.

• fluxrope – Overplot a contour of where vg_fluxrope is under the cutoff value given in this variable. The contour follows the AMR cell edges.

• fluxropelinewidth – Line width of fluxrope contour, default 0.5.

• fluxropecolour – Colour of fluxrope contour, default “black”.

• fluxropelinestyle – Line style of fluxrope contour, default “solid”.

• amr – Overplot contours of AMR levels given as a tuple in this argument. The contours follow the AMR cell edges.

• amrlinewidths – Line widths of AMR contours, default 0.5. If a single value it is applied to all contours, otherwise given as a tuple of same length as kwarg amr.

• amrcolours – Colours of AMR contour, default “black”. If a single value is given, it is applied to all contours, otherwise given as a tuple of same length as kwarg amr.

• amrlinestyles – Line styles of AMR contours, default “solid”. If a single value is given, it is applied to all contours, otherwise given as a tuple of same length as kwarg amr.

• nomask – Do not mask plotting based on proton density

• vectors – Set to a vector variable to overplot (unit length vectors, color displays variable magnitude)

• vectordensity – Aim for how many vectors to show in plot window (default 100)

• vectorcolormap – Colormap to use for overplotted vectors (default: gray)

• vectorsize – Scaling of vector sizes

• streamlines – Set to a vector variable to overplot as streamlines

• streamlinedensity – Set streamline density (default 1)

• streamlinecolor – Set streamline color (default white)

• streamlinethick – Set streamline thickness

• axes – Provide the routine a set of axes to draw within instead of generating a new image. It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar to be automatically added next to the panel (but this may affect the overall layout) Note that the aspect ratio of the colormap is made equal in any case, hence the axes proportions may change if the box and axes size are not designed to match by the user

• cbaxes – Provide the routine a set of axes for the colourbar.

• cb_horizontal – Set to draw the colorbar horizontally instead of vertically (default: False) requires cbaxes to be set.

• normal – Direction of the normal of the 2D cut through (‘x’, ‘y’, or ‘z’ or a vector along x,y, or z)

• cutpoint – Coordinate (in normal direction) through which the cut must pass [m]

• cutpointre – Coordinate (in normal direction) through which the cut must pass [rE]

• flipxaxis – Invert output plot x/horizontal axis so that e.g. the Sun is on the left (default: False)

• useimshow – Use imshow for raster background instead (default: False)

• imshowinterp – Use this matplotlib interpolation for imshow (default: ‘none’)

Returns:

Outputs an image to a file or to the screen.

analysator.plot.plot_ionosphere(filename=None, vlsvobj=None, filedir=None, step=None, run=None, outputdir=None, outputfile=None, nooverwrite=False, var=None, op=None, operator=None, colormap=None, vmin=None, vmax=None, symmetric=False, absolute=None, usesci=True, log=None, lin=None, symlog=None, nocb=False, internalcb=False, minlatitude=60, cbtitle=None, title=None, cbaxes=None, cb_horizontal=False, thick=1.0, scale=1.0, vscale=1.0, wmark=False, wmarkb=False, viewdir=1.0, draw=None, axes=None)

Plots a 2d projection of an ionosphere variable

Parameters:

• filename – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• run – run identifier, used for constructing output filename

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final part will be used as a prefix for the files.

• outputfile – Singular output file name

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• var – variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, E, B, v, V or others. Accepts any variable known by analysator. Per-population variables are simply given as “proton/rho” etc

• operator – Operator to apply to variable: None, x, y, or z. Vector variables return either the queried component, or otherwise the magnitude.

• op – duplicate of operator

• colormap – colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, magma, parula, nipy_spectral, RdBu, bwr

• vmin,vmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot (non-zero rho regions only) are used.

• symmetric – Set the absolute value of vmin and vmax to the greater of the two

• absolute – Plot the absolute of the evaluated variable

• usesci – Use scientific notation for colorbar ticks? (default: True)

• lin – Flag for using linear colour scaling instead of log

• symlog – Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. Allows symmetric quasi-logarithmic plots of e.g. transverse field components. A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can result in the innermost tick marks overlapping. In this case, using a larger value for symlog is suggested.

• nocb – Set to suppress drawing of colourbar

• internalcb – Set to draw colorbar inside plot instead of outside. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• minlatitude – Minimum plot latitude (default=60 degrees)

• title – string to use as plot title instead of time. Special case: Set to “msec” to plot time with millisecond accuracy or “musec” for microsecond accuracy. “sec” is integer second accuracy.

• cbtitle – string to use as colorbar title instead of map name

• viewdir – view direction onto the sphere. Positive value: North pole. Negative values: South pole.

• scale – Scale text size (default=1.0)

• vscale – Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 or from tesla to nanotesla. Guesses correct units for colourbar for some known variables.

• axes – Provide the routine a set of axes to draw within instead of generating a new image.

• cbaxes – Provide the routine a set of axes for the colourbar.

• cb_horizontal – Set to draw the colorbar horizontally instead of vertically (default: False) requires cbaxes to be set.

• thick – line and axis thickness, default=1.0

• draw – Set to anything but None or False in order to draw image on-screen instead of saving to file (requires x-windowing)

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• wmarkb – As for wmark, but uses an all-black Vlasiator logo.

analysator.plot.plot_isosurface(filename=None, vlsvobj=None, filedir=None, step=None, outputdir=None, outputfile=None, nooverwrite=None, surf_var=None, surf_op=None, surf_level=None, color_var=None, color_op=None, surf_step=1, title=None, cbtitle=None, draw=None, usesci=None, symmetric=False, highres=None, boxm=[], boxre=[], colormap=None, run=None, wmark=None, nocb=False, unit=None, thick=1.0, scale=1.0, vscale=1.0, vmin=None, vmax=None, lin=None, symlog=None, angle=[30.0, 90.0], transparent=True)

Plots a coloured isosurface plot with axes and a colour bar.

Parameters:

• filename – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final parti will be used as a perfix for the files.

• outputfile – Full path to output file, will make directory if it does not exist. Overrides outputdir.

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• surf_var – Variable to read for defining surface

• surf_op – Operator to use for variable to read surface

• surf_level – Level at which to define surface

• surf_step – Vertex stepping for surface generation: larger value returns coarser surface

• color_var – Variable to read for coloring surface

• color_op – Operator to use for variable to color surface (‘x’, ‘y’, ‘z’; if None and color_var is a vector, the magnitude is taken)

• boxm – zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box)

• boxre – zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box)

• colormap – colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, magma, parula, nipy_spectral, RdBu, bwr

• run – run identifier, used for constructing output filename

• title – string to use as plot title instead of time

• cbtitle – string to use as colorbar title instead of map name

• unit – Plot axes using 10^{unit} m (default: Earth radius R_E)

• usesci – Use scientific notation for colorbar ticks? (default: 1)

• vscale – Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 or from tesla to nanotesla. Guesses correct units for colourbar for some known variables. Set to None to seek for a default scaling.

• vmin,vmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot (non-zero rho regions only) are used.

• symmetric – Set the absolute value of vmin and vmax to the greater of the two

• lin – Flag for using linear colour scaling instead of log

• symlog – Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. Allows symmetric quasi-logarithmic plots of e.g. transverse field components. A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2.

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner.

• highres – Creates the image in high resolution, scaled up by this value (suitable for logging.info).

• draw – Set to nonzero in order to draw image on-screen instead of saving to file (requires x-windowing)

• transparent – Set to False in order to make the surface opaque

• scale – Scale text size (default=1.0)

• thick – line and axis thickness, default=1.0

• nocb – Set to suppress drawing of colourbar

• angle – Viewing elevation and azimuthal angles in degrees

Returns:

Outputs an image to a file or to the screen.

analysator.plot.plot_multiple_variables(variables_x_list, variables_y_list, figure=[], clean_xticks=False)

Plots multiple variables from the input with pylab

Parameters:

• variables_x_list – Some list of variables to be plotted in the x-axis

• variables_y_list – Some list of variables to be plotted in the y-axis

• figure – If one wants to plot into an existing figure then the matplotlib figure should be passed as an argument (OPTIONAL)

Returns:

a pylab figure with the plot

#Example usage:
plot_multiple_variables( [distances, xcoordinates], [rho, B_x] )
# This would plot rho_values as a function of distance and B_x_values as a function of xcoordinates

Note

Multiplot expects variables to be saved in the VariableInfo class

Note

If for some reason some variable list (x or y) is empty, e.g. variables_x_list = [B_x, [], B_z, rho], then the variable will not be plotted. This can be used if one wants to plot only into certain subplots.

analysator.plot.plot_neutral_sheet(filename=None, vlsvobj=None, filedir=None, step=None, run=None, outputdir=None, outputfile=None, nooverwrite=False, var=None, op=None, operator=None, title=None, cbtitle=None, draw=None, usesci=True, symlog=None, boxm=None, boxre=None, colormap=None, nocb=False, internalcb=False, wmark=False, wmarkb=False, axisunit=None, thick=1.0, scale=1.0, tickinterval=0, noborder=False, noxlabels=False, noylabels=False, vmin=None, vmax=None, lin=None, external=None, expression=None, diff=None, vscale=1.0, absolute=False, symmetric=False, pass_vars=None, pass_times=None, pass_full=False, nomask=None, Earth=None, highres=None, vectors=None, vectordensity=100, vectorcolormap='gray', vectorsize=1.0, streamlines=None, streamlinedensity=1, streamlinecolor='white', streamlinethick=1.0, axes=None, cbaxes=None, cb_horizontal=False, useimshow=False, imshowinterp='none', folding_alpha=0.2, z_extent=[-5, 5], sheetlayer='above')

Plots a coloured plot along the neutral sheet with axes and a colour bar.

Parameters:

• filename – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• run – run identifier, used for constructing output filename

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final part will be used as a prefix for the files.

• outputfile – Singular output file name

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• var – variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, E, B, v, V or others. Accepts any variable known by analysator. Per-population variables are simply given as “proton/rho” etc

• operator – Operator to apply to variable: None, x, y, or z. Vector variables return either the queried component, or otherwise the magnitude.

• op – duplicate of operator

• boxm – zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box)

• boxre – zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box)

• colormap – colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, magma, parula, nipy_spectral, RdBu, bwr

• title – string to use as plot title instead of time. Special case: Set to “msec” to plot time with millisecond accuracy or “musec” for microsecond accuracy. “sec” is integer second accuracy.

• cbtitle – string to use as colorbar title instead of map name

• axisunit – Plot axes using 10^{axisunit} m (default: Earth radius R_E)

• tickinterval – Interval at which to have ticks on axes (not colorbar)

• usesci – Use scientific notation for colorbar ticks? (default: True)

• vmin,vmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot (non-zero rho regions only) are used.

• symmetric – Set the absolute value of vmin and vmax to the greater of the two

• lin – Flag for using linear colour scaling instead of log

• symlog – Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. Allows symmetric quasi-logarithmic plots of e.g. transverse field components. A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can result in the innermost tick marks overlapping. In this case, using a larger value for symlog is suggested.

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• wmarkb – As for wmark, but uses an all-black Vlasiator logo.

• Earth – If set, draws an earth at (0,0)

• highres – Creates the image in high resolution, scaled up by this value (suitable for print).

• draw – Set to nonzero in order to draw image on-screen instead of saving to file (requires x-windowing)

• noborder – Plot figure edge-to-edge without borders (default off)

• noxlabels – Suppress x-axis labels and title

• noylabels – Suppress y-axis labels and title

• scale – Scale text size (default=1.0)

• thick – line and axis thickness, default=1.0

• nocb – Set to suppress drawing of colourbar

• internalcb – Set to draw colorbar inside plot instead of outside. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• external – Optional function to use for external plotting of e.g. contours. The function receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps If the function accepts a fifth variable, if set to true, it is expected to return a list of required variables for constructing the pass_maps dictionary. See note under expression about the dictionaries of arrays.

• expression – Optional function which calculates a custom expression to plot. The function receives the same dictionary of numpy arrays as external, as an argument pass_maps, the contents of which are maps of variables. Each is either of size [ysize,xsize] or for multi-dimensional variables (vectors, tensors) it’s [ysize,xsize,dim]. If the function accepts a second variable, if set to true, it is expected to return a list of required variables for pass_maps. Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions on, see the plot_helpers.py file.

• vscale – Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 or from tesla to nanotesla. Guesses correct units for colourbar for some known variables. Set to None to seek for a default scaling.

• absolute – Plot the absolute of the evaluated variable

• pass_vars – Optional list of map names to pass to the external/expression functions as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or for multi-dimensional variables (vectors, tensors) it’s [ysize,xsize,dim].

• pass_times – Integer, how many timesteps in each direction should be passed to external/expression functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If pass_times has two values, the first is the extent before, the second after. (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps for a total of four timesteps) This causes pass_vars to become a list of timesteps, with each timestep containing a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is added as ‘dstep’ which gives the timestep offset from the master frame. Does not work if working from a vlsv-object.

• pass_full – Set to anything but None in order to pass the full arrays instead of a zoomed-in section

• diff – Instead of a regular plot, plot the difference between the selected plot type for the regular source file and the file given by this keyword. This overides external and expression keywords, as well as related pass_vars, pass_times, and pass_full.

• z_extent – Search bracket for the neutral sheet in axisunit units

• folding_alpha – If non-zero, plots transparent dots over the regions where the sheet has multiple separate z-values. A value of 1.0 is opaque, a value of 0.0 is transparent.

• sheetlayer – If set to ‘above’, plots the topmost layer of the neutral sheet in case of folding. If set to anything else, the downmost layer is plotted.

• nomask – Do not mask plotting based on proton density

• vectors – Set to a vector variable to overplot (unit length vectors, color displays variable magnitude)

• vectordensity – Aim for how many vectors to show in plot window (default 100)

• vectorcolormap – Colormap to use for overplotted vectors (default: gray)

• vectorsize – Scaling of vector sizes

• streamlines – Set to a vector variable to overplot as streamlines

• streamlinedensity – Set streamline density (default 1)

• streamlinecolor – Set streamline color (default white)

• streamlinethick – Set streamline thickness

• axes – Provide the routine a set of axes to draw within instead of generating a new image. It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar to be automatically added next to the panel (but this may affect the overall layout) Note that the aspect ratio of the colormap is made equal in any case, hence the axes proportions may change if the box and axes size are not designed to match by the user

• cbaxes – Provide the routine a set of axes for the colourbar.

• cb_horizontal – Set to draw the colorbar horizontally instead of vertically (default: False) requires cbaxes to be set.

• normal – Direction of the normal of the 2D cut through (‘x’, ‘y’, or ‘z’ or a vector)

• cutpoint – Coordinate (in normal direction) through which the cut must pass [m]

• cutpointre – Coordinate (in normal direction) through which the cut must pass [rE]

• useimshow – Use imshow for raster background instead (default: False)

• imshowinterp – Use this matplotlib interpolation for imshow (default: ‘none’)

Returns:

Outputs an image to a file or to the screen.

analysator.plot.plot_threeslice(filename=None, vlsvobj=None, filedir=None, step=None, run=None, outputdir=None, outputfile=None, nooverwrite=False, var=None, op=None, operator=None, boxm=None, boxre=None, colormap=None, vmin=None, vmax=None, symmetric=False, absolute=None, lin=None, symlog=None, nocb=False, cbtitle=None, title=None, halfaxes=False, usesci=True, axisunit=None, axiscolor=None, shadings=None, draw=None, tickinterval=None, fixedticks=False, pass_full=None, wmark=False, wmarkb=False, nomask=None, Earth=True, thick=1.0, scale=1.0, expression=None, vscale=1.0, viewangle=(-60.0, 30.0), cutpointm=None, cutpointre=None, slices=None)

Plots a 3d plot constructed of three 2d cut throughs.

Parameters:

• filename – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• run – run identifier, used for constructing output filename

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final part will be used as a prefix for the files.

• outputfile – Singular output file name

• draw – Set to anything but None or False in order to draw image on-screen instead of saving to file (requires x-windowing)

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• var – variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, E, B, v, V or others. Accepts any variable known by analysator. Per-population variables are simply given as “proton/rho” etc

• operator – Operator to apply to variable: None, x, y, or z. Vector variables return either the queried component, or otherwise the magnitude.

• op – duplicate of operator

• boxm – zoom box extents [x0,x1,y0,y1,z0,z1] in metres (default and truncate to: whole simulation box)

• boxre – zoom box extents [x0,x1,y0,y1,z0,z1] in Earth radii (default and truncate to: whole simulation box)

• colormap – colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, magma, parula, nipy_spectral, RdBu, bwr

• vmin,vmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot (non-zero rho regions only) are used.

• symmetric – Set the absolute value of vmin and vmax to the greater of the two

• absolute – Plot the absolute of the evaluated variable

• lin – Flag for using linear colour scaling instead of log

• symlog – Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. Allows symmetric quasi-logarithmic plots of e.g. transverse field components. A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can result in the innermost tick marks overlapping. In this case, using a larger value for symlog is suggested.

• nocb – Set to suppress drawing of colourbar

• title – string to use as plot title instead of time. Special case: Set to “msec” to plot time with millisecond accuracy or “musec” for microsecond accuracy. “sec” is integer second accuracy.

• cbtitle – string to use as colorbar title instead of map name

• halfaxes – Flag to prevent plotting the hidden half of the axes, otherwise shown as dashed lines (default: False)

• usesci – Use scientific notation for colorbar ticks? (default: True)

• axisunit – Plot axes using 10^{axisunit} m (default: Earth radius R_E)

• axiscolor – Color for drawing axes (default black)

• shadings – Dimming values for the surfaces normal to the X, Y, Z directions, respectively, to better distinguish the slices, e.g. “(0.6,0.8,1.0). Default using the angles between the surface normal directions and the viewing angle.

• (default (tickinterval:Axis tick interval, expressed in 10^{axisunit}) – 10 Earth radii)

• fixedticks – Set ticks at fixed locations instead of relative to the triple cut point (default: False)

• pass_full – Set to anything but None in order to pass the full arrays instead of a zoomed-in section

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• wmarkb – As for wmark, but uses an all-black Vlasiator logo.

• nomask – Do not mask plotting based on proton density

• Earth – Draw Earth at origin (default True)

• scale – Scale text size (default=1.0)

• thick – line and axis thickness, default=1.0

• expression – Optional function which calculates a custom expression to plot. The function receives the same dictionary of numpy arrays as external, as an argument pass_maps, the contents of which are maps of variables. Each is either of size [ysize,xsize] or for multi-dimensional variables (vectors, tensors) it’s [ysize,xsize,dim]. If the function accepts a second variable, if set to true, it is expected to return a list of required variables for pass_maps. Important note: the dictionaries of arrays passed to expression are of shape [ysize,xzize], so for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions on, see the plot_helpers.py file.

• vscale – Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 or from tesla to nanotesla. Guesses correct units for colourbar for some known variables. Set to None to search for a default scaling.

• viewangle – Azimuth and elevation angles giving the point of view on the 3D axes, in degrees. (default=(-60.,30.); corresponds to dayside, morningside, northern hemisphere)

• cutpointm – Coordinates of the point through which all three 2D cuts must pass [m]

• cutpointre – Coordinates of the point through which all three 2D cuts must pass [rE]

• slices – Normal directions of the slices to plot, default=’xyz’

analysator.plot.plot_variables(x, y, figure=[])

Plots x and y variables from the input with pylab

Parameters:

• x – Some variable to be plotted in the x-axis

• y – Some variable to be plotted in the y-axis

• figure – If one wants to plot into an existing figure then the matplotlib figure should be passed as an argument (OPTIONAL)

Returns:

a pylab figure with the plot

# Example usage:
plot_variables( distances, rho )
# This would plot rho as a function of distance

analysator.plot.plot_vdf(filename=None, vlsvobj=None, filedir=None, step=None, cellids=None, pop='proton', coordinates=None, coordre=None, outputdir=None, outputfile=None, nooverwrite=None, draw=None, axisunit=None, axiskmps=None, title=None, cbtitle=None, tickinterval=None, colormap=None, box=None, nocb=None, internalcb=None, run=None, thick=1.0, wmark=None, wmarkb=None, fmin=None, fmax=None, slicethick=None, reducer='integrate', resampler=True, cellsize=None, xy=None, xz=None, yz=None, normal=None, normalx=None, bpara=None, bpara1=None, bperp=None, coordswap=None, bvector=None, bvectorscale=0.2, cbulk=None, cpeak=None, center=None, wflux=None, setThreshold=None, noborder=None, scale=1.0, scale_text=8.0, scale_title=10.0, scale_cb=5.0, scale_label=12.0, biglabel=None, biglabloc=None, noxlabels=None, noylabels=None, axes=None, cbaxes=None, cb_horizontal=False, contours=None, figsize=None)

Plots a coloured 2D plot of a VDF (a slice of given thickness or fully projected) with axes and a colour bar.

Parameters:

• filename – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final parti will be used as a perfix for the files.

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• cellids – LIST of cell IDs to plot VDF for

• coordinates – LIST of 3-element spatial coordinate lusts to plot VDF for (given in metres)

• coordre – LIST of 3-element spatial coordinate lists to plot VDF for (given in Earth radii)

• pop – Population to plot, default proton

• colormap – colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, magma, parula, nipy_spectral, RdBu, bwr

• run – run identifier, used for constructing output filename

• title – string to use as plot title instead of time. Special case: Set to “msec” to plot time with millisecond accuracy or “musec” for microsecond accuracy. “sec” is integer second accuracy.

• cbtitle – string to use as colorbar title instead of phase space density of flux

• contours – Set to number of contours to draw

• fmin,fmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot are used.

• box – extents of plotted velocity grid as [x0,x1,y0,y1] (in m/s)

• axisunit – Plot v-axes using 10^{axisunit} m/s (default: km/s)

• axiskmps – Plot v-axes using 10^{axiskmps} km/s (default: km/s, when the kwarg has a value)

• tickinterval – Interval at which to have ticks on axes

• xy – Perform slice in x-y-direction

• xz – Perform slice in x-z-direction

• yz – Perform slice in y-z-direction

• normal – Perform slice in plane perpendicular to given vector

• normalx – X-axis direction for slice in plane perpendicular to given vector

• bpara – Perform slice in B_para / B_perp2 plane

• bpara1 – Perform slice in B_para / B_perp1 plane

• bperp – Perform slice in B_perp1 / B_perp2 plane If no plane is given, default is simulation plane (for 2D simulations)

• coordswap – Swap the parallel and perpendicular coordinates

• bvector – Plot a magnetic field vector projection in-plane

• bvectorscale – Scale of bvector (default: 0.2 in units of axis lengths)

• cbulk – Center plot on position of total bulk velocity (or if not available, bulk velocity for this population)

• cpeak – Center plot on velocity associated with highest (peak) phase-space density for this population)

• center – Center plot on provided 3-element velocity vector position (in m/s) If set instead to “bulk” will center on bulk velocity If set instead to “peak” will center on velocity with highest phase-space density

• wflux – Plot flux instead of distribution function

• slicethick – Thickness of slice as multiplier of cell size (default: 1 or minimum for good coverage). This can be set to zero in order to project the whole VDF to a plane.

• reducer – How to reduce to 2D - default ‘integrate’ for LOS integration and reduced units, ‘average’ for old (slightly questionable) behaviour

• resampler – Resample onto a regular grid? Default: yes, use False to disable.

• cellsize – Plotting grid cell size as multiplier of input cell size (default: 1 or minimum for good coverage)

• setThreshold – Use given setThreshold value instead of EffectiveSparsityThreshold or MinValue value read from file Useful if EffectiveSparsityThreshold wasn’t saved, or user wants to draw buffer cells with values below the sparsity threshold

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• wmarkb – As for wmark, but uses an all-black Vlasiator logo.

• draw – Draw image on-screen instead of saving to file (requires x-windowing)

• nocb – Suppress plotting of colourbar legend

• internalcb – Set to draw colorbar inside plot instead of outside. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• biglabel – Plot large label (in top-left corner)

• biglabloc – Move large label to: 0: NW 1: NE 2: SE 3: SW corner

• axes – Provide the routine a set of axes to draw within instead of generating a new image.

• cbaxes – Provide the routine a set of axes for the colourbar.

• cb_horizontal – If true, use a horizontal colorbar (this will look stupid unless you specify cbaxes)

• noborder – Plot figure edge-to-edge without borders (default off)

• noxlabels – Suppress x-axis labels and title

• noylabels – Suppress y-axis labels and title

• scale – Scale text size everywhere (default=1.0)

• scale_text – Most text additional scale factor (default=8.0)

• scale_title – Title additional scale factor (default=10.0)

• scale_cb – Colour bar text additional scale factor (default=5.0)

• scale_label – Big label text additional scale factor (default=12.0)

• thick – line and axis thickness, default=1.0

• figsize – Set figure size, default=None which will use [4.0,3.15*ratio]

Returns:

Outputs an image to a file or to the screen.

# Example usage:

pt.plot.plot_vdf(filename="/proj/vlasov/2D/ABC/distributions/distributions.0000100.vlsv",
                 coordre=[[11.7,-1.6,0.]], cbulk=1, bpara=1,box=[-2e6,2e6,-2e6,2e6],draw=1)

pt.plot.plot_vdf(filename="/proj/vlasov/2D/ABC/distributions/distributions.0000100.vlsv",
                 cellids=1670561, xy=1, box=[-2e6,2e6,-2e6,2e6], slicethick=5)

pt.plot.plot_vdf(filename="/proj/vlasov/2D/ABC/distributions/distributions.0000100.vlsv",
                 cellids=[1670561,], xz=1, box=[-2e6,2e6,-2e6,2e6], slicethick=0)

Note tilted slices: By default, the program samples the V-space with a slice where each cell is cube the dimensions of which are found by performing a rotation on a sample square and finding the maximum xyz-extent. This ensures adequate coverage and decreases sampling effects. This behaviour can be overridden with the slicethick and cellsize keywords.

Setting a value of slicethick=0 will result in the whole VDF being flattened into a single plane. This may result in some slight sampling artefacts, but is a good measure of complex populations.

analysator.plot.plot_vdf_profiles(filename=None, vlsvobj=None, filedir=None, step=None, cellids=None, pop='proton', coordinates=None, coordre=None, outputdir=None, outputfile=None, nooverwrite=None, draw=None, axisunit=None, title=None, tickinterval=None, lin=None, run=None, thick=1.0, wmark=None, wmarkb=None, fmin=None, fmax=None, vmin=None, vmax=None, xy=None, xz=None, yz=None, normal=None, bpara=None, bpara1=None, bperp=None, cbulk=None, cpeak=None, center=None, setThreshold=None, axes=None)

Plots vdf values along axis-aligned lines (see axis definitions).

Parameters:

• filename – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final parti will be used as a perfix for the files.

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• cellids – LIST of cell IDs to plot VDF for

• coordinates – LIST of 3-element spatial coordinate lusts to plot VDF for (given in metres)

• coordre – LIST of 3-element spatial coordinate lists to plot VDF for (given in Earth radii)

• pop – Population to plot, default proton

• run – run identifier, used for constructing output filename

• title – string to use as plot title instead of time. Special case: Set to “msec” to plot time with millisecond accuracy or “musec” for microsecond accuracy. “sec” is integer second accuracy.

• fmin,fmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot are used.

• vmin,vmax – min and max values for x-axis

• axisunit – Plot v-axes using 10^{axisunit} m/s (default: km/s)

• tickinterval – Interval at which to have ticks on axes

• lin – Plot using linear y-axis (default log)

• xy – Perform slice in x-y-direction

• xz – Perform slice in x-z-direction

• yz – Perform slice in y-z-direction

• normal – Perform slice in plane perpendicular to given vector

• bpara – Perform slice in B_para / B_perp2 plane

• bpara1 – Perform slice in B_para / B_perp1 plane

• bperp – Perform slice in B_perp1 / B_perp2 plane If no plane is given, default is simulation plane (for 2D simulations)

• cbulk – Center plot on position of total bulk velocity (or if not available, bulk velocity for this population)

• cpeak – Center plot on velocity with highest phase-space density

• center – Center plot on provided 3-element velocity vector position (in m/s) If set instead to “bulk” will center on bulk velocity If set instead to “peak” will center on velocity with highest phase-space density

• setThreshold – Use given setThreshold value instead of EffectiveSparsityThreshold or MinValue value read from file Useful if EffectiveSparsityThreshold wasn’t saved, or user wants to draw buffer cells with values below the sparsity threshold

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• wmarkb – As for wmark, but uses an all-black Vlasiator logo.

• draw – Draw image on-screen instead of saving to file (requires x-windowing)

• axes – Provide the routine a set of axes to draw within instead of generating a new image.

• scale – Scale text size (default=1.0)

• thick – line and axis thickness, default=1.0

Returns:

Outputs an image to a file or to the screen.

# Example usage:

pt.plot.plot_vdf(filename="/proj/vlasov/2D/ABC/distributions/distributions.0000100.vlsv",
                 coordre=[[11.7,-1.6,0.]], cbulk=1, bpara=1,box=[-2e6,2e6,-2e6,2e6],draw=1)

pt.plot.plot_vdf(filename="/proj/vlasov/2D/ABC/distributions/distributions.0000100.vlsv",
                 cellids=1670561, xy=1, box=[-2e6,2e6,-2e6,2e6], slicethick=5)

pt.plot.plot_vdf(filename="/proj/vlasov/2D/ABC/distributions/distributions.0000100.vlsv",
                 cellids=[1670561,], xz=1, box=[-2e6,2e6,-2e6,2e6], slicethick=0)

Note tilted slices: By default, the program samples the V-space with a slice where each cell is cube the dimensions of which are found by performing a rotation on a sample square and finding the maximum xyz-extent. This ensures adequate coverage and decreases sampling effects. This behaviour can be overridden with the slicethick and cellsize keywords.

Setting a value of slicethick=0 will result in the whole VDF being flattened into a single plane. This may result in some slight sampling artefacts, but is a good measure of complex populations.

analysator.plot.plot_vdfdiff(filename1=None, filename2=None, vlsvobj1=None, vlsvobj2=None, filedir=None, step=None, step_diff=None, cellids=None, cellids2=None, pop='proton', coordinates=None, coordre=None, outputdir=None, outputfile=None, nooverwrite=None, draw=None, axisunit=None, axiskmps=None, title=None, cbtitle=None, tickinterval=None, colormap=None, box=None, nocb=None, internalcb=None, run=None, thick=1.0, wmark=None, wmarkb=None, fmin=None, fmax=None, slicethick=None, reducer='integrate', resampler=False, cellsize=None, xy=None, xz=None, yz=None, normal=None, normalx=None, bpara=None, bpara1=None, bperp=None, coordswap=None, bvector=None, bvectorscale=0.2, cbulk=None, center=None, wflux=None, setThreshold=None, noborder=None, scale=1.0, scale_text=8.0, scale_title=10.0, scale_cb=5.0, scale_label=12.0, biglabel=None, biglabloc=None, noxlabels=None, noylabels=None, axes=None, cbaxes=None, cb_horizontal=False, contours=None)

Plots the difference between VDFs as a coloured 2D plot with axes and a colour bar.

Parameters:

• filename1 – path to .vlsv file to use for input. Assumes a bulk file.

• filename2 – path to .vlsv file to use for input. Assumes a bulk file.

• vlsvobj1 – Optionally provide a python vlsvfile object instead

• vlsvobj2 – Optionally provide a python vlsvfile object instead

• filedir – Optionally provide directory where files are located and use step for bulk file name

• step – output step index, used for constructing output (and possibly input) filename

• step_diff – the second step index to use for a file in case filedir is used

• outputdir – path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) If directory does not exist, it will be created. If the string does not end in a forward slash, the final parti will be used as a perfix for the files.

• nooverwrite – Set to only perform actions if the target output file does not yet exist

• cellids – LIST of cell IDs to plot VDF for

• cellids2 – Optional: LIST of cell IDs from input file 2. Same as cellids if omitted.

• coordinates – LIST of 3-element spatial coordinate lusts to plot VDF for (given in metres)

• coordre – LIST of 3-element spatial coordinate lists to plot VDF for (given in Earth radii)

• pop – Population to plot, default proton

• colormap – colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, magma, parula, nipy_spectral, RdBu, bwr

• run – run identifier, used for constructing output filename

• title – string to use as plot title instead of time. Special case: Set to “msec” to plot time with millisecond accuracy or “musec” for microsecond accuracy. “sec” is integer second accuracy.

• cbtitle – string to use as colorbar title instead of phase space density of flux

• contours – Set to number of contours to draw

• fmin,fmax – min and max values for colour scale and colour bar. If no values are given, min and max values for whole plot are used.

• box – extents of plotted velocity grid as [x0,x1,y0,y1] (in m/s)

• axisunit – Plot v-axes using 10^{axisunit} m/s (default: km/s)

• axiskmps – Plot v-axes using 10^{axiskmps} km/s (default: km/s, when the kwarg has a value)

• tickinterval – Interval at which to have ticks on axes

• xy – Perform slice in x-y-direction

• xz – Perform slice in x-z-direction

• yz – Perform slice in y-z-direction

• normal – Perform slice in plane perpendicular to given vector

• normalx – X-axis direction for slice in plane perpendicular to given vector

• bpara – Perform slice in B_para / B_perp2 plane

• bpara1 – Perform slice in B_para / B_perp1 plane

• bperp – Perform slice in B_perp1 / B_perp2 plane If no plane is given, default is simulation plane (for 2D simulations)

• coordswap – Swap the parallel and perpendicular coordinates

• bvector – Plot a magnetic field vector projection in-plane

• bvectorscale – Scale of bvector (default: 0.2 in units of axis lengths)

• cbulk – Center plot on position of total bulk velocity (or if not available, bulk velocity for this population)

• center – Center plot on provided 3-element velocity vector position (in m/s) If set instead to “bulk” will center on bulk velocity If set instead to “peak” will center on velocity with highest phase-space density

• wflux – Plot flux instead of distribution function

• slicethick – Thickness of slice as multiplier of cell size (default: 1 or minimum for good coverage). This can be set to zero in order to project the whole VDF to a plane.

• reducer – How to reduce to 2D - default ‘integrate’ for LOS integration and reduced units, ‘average’ for old (slightly questionable) behaviour

• resampler – Resample onto a regular grid? Default: yes, use False to disable.

• cellsize – Plotting grid cell size as multiplier of input cell size (default: 1 or minimum for good coverage)

• setThreshold – Use given setThreshold value instead of EffectiveSparsityThreshold or MinValue value read from file Useful if EffectiveSparsityThreshold wasn’t saved, or user wants to draw buffer cells with values below the sparsity threshold

• wmark – If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• wmarkb – As for wmark, but uses an all-black Vlasiator logo.

• draw – Draw image on-screen instead of saving to file (requires x-windowing)

• nocb – Suppress plotting of colourbar legend

• internalcb – Set to draw colorbar inside plot instead of outside. If set to a text string, tries to use that as the location, e.g. “NW”,”NE”,”SW”,”SW”

• biglabel – Plot large label (in top-left corner)

• biglabloc – Move large label to: 0: NW 1: NE 2: SE 3: SW corner

• axes – Provide the routine a set of axes to draw within instead of generating a new image.

• cbaxes – Provide the routine a set of axes for the colourbar.

• cb_horizontal – If true, use a horizontal colorbar (this will look stupid unless you specify cbaxes)

• noborder – Plot figure edge-to-edge without borders (default off)

• noxlabels – Suppress x-axis labels and title

• noylabels – Suppress y-axis labels and title

• scale – Scale text size everywhere (default=1.0)

• scale_text – Most text additional scale factor (default=8.0)

• scale_title – Title additional scale factor (default=10.0)

• scale_cb – Colour bar text additional scale factor (default=5.0)

• scale_label – Big label text additional scale factor (default=12.0)

• thick – line and axis thickness, default=1.0

Returns:

Outputs an image to a file or to the screen.

# Example usage:

pt.plot.plot_vdfdiff("bulk.0000040.vlsv","bulk.0000048.vlsv",cellids=1,xy=1,slicethick=1,colormap="seismic",
                 fmin=-1e-9,fmax=1e-9,cbulk=1)

See documentation of plot_vdf() for more usage information.