VISAN Reference Manual

Much of VISAN's functionality is provided by Python and the Numpy package, which are both part of VISAN. For an overview of the functions provided by these two components please look at the Python and Numpy documentation.

Contents

Plotting functions

plot(...)

Display a 2-dimensional plot of a dataset.

The plot() function has several different usage modes, and can take a large number of optional keywords.

Basic usage:

>>> plot(ydata)

where 'ydata' is a one-dimensional Python list or numpy array, will plot the 'ydata' values on the vertical axis against an index array [0..len(data)] on the horizontal axis, in a single plot frame.

If 'ydata' is a two-dimensional n x m numpy array, a sequence of n plot frames will be created. Each frame f will show a plot of the ydata[f,:] values against an index array [0..m-1] on the horizontal axis. Initially, only the first frame is shown. The user can start an animation sequence which will cycle through the successive frames in the plot window.

>>> plot(xdata, ydata)

where 'xdata' and 'ydata' are both one-dimensional, will plot the 'ydata' values on the vertical axis against the corresponding 'xdata' values on the horizontal axis.

If 'ydata', or 'xdata' and 'ydata' are two-dimensional n x m numpy arrays, a sequence of n plot frames will be created. Each frame f will show a plot of the ydata[f,:] values against the xdata[f,:] value, or against xdata[0] values if xdata is one-dimensional. Initially, only the first frame is shown. The user can start an animation sequence which will cycle through the successive frames in the plot window.

>>> plot(harpproduct)

where 'harpproduct' is an object of type harp.Product (see also the documentation for the HARP Python interface), will display a specific 2D plot associated with the type of data contained in the 'harpproduct'.

>>> plot(harpproduct, value='variablename')

by using the value parameter you can select which variable from the HARP product should be used to generate the 2D plot.

By default, plot() creates and displays a new plot window. However:

>>> w = plot(data1)
>>> plot(data2, window=w)

will plot data2 in the same window 'w' as used for data1, instead of opening a separate window.

In addition to the 'window' keyword, the plot() function also accepts a number of other, comma-separated optional properties of the form 'property=value'. Their order is arbitrary, but they must always appear after any data arguments to the plot() function. For example:

>>> plot(xydata, linewidth=2, points=True, color=(0.1, 0.5, 0.3))

Specifying a property multiple times in the same plot() command is not allowed and will lead to a Syntax Error if attempted.

There are two types of properties: plot properties and dataset properties. A plot property applies 'globally', i.e., plot-wide. If the property is supplied multiple times in consecutive plot() function calls to the same plot window, the last supplied value will take precedence and override any previously specified values. You can also specify dataset properties which will have an effect on each separate dataset plotted to a window. The available plot properties for plot() are:

PLOT PROPERTIES FOR plot()
keyword description type default value constraints
window The window to plot the dataset in. <plotwindow handle>
the return value of a previous plot() command
create a new window Value should refer to a valid window that has not yet been closed or otherwise destroyed.
windowtitle Set the window title of the plotwindow. string 'VISAN 2D Plot'  
size Set the initial size of the plot window, in (width, height) pixels. This property only has an effect when specified in the plot() command that creates the plot window. It is ignored when specified for any subsequent plot into that window. 2-element tuple (800, 494)
(Golden Ratio)
0 < width < maximum screen width
0 < height < maximum screen height
pos Set the initial position of the plot window, in (x, y) left-upper corner based coordinates. 2-element tuple <calculated>
New windows are placed a bit down and to the right with regard to the previously opened window. When there is no further space left, a new window will be created in the top left corner of the screen.
0 < x < maximum screen width
0 < y < maximum screen height
title Set the plot title. This title is centered at the top of the plot panel. string no title
xrange Set the bounds for the plot's x-axis values. If the resulting range contains elements <= 0, the xlog property will be set to False. 2-element sequence (Python tuple or list) of doubles. <Derive from data>
Calculate the minimal range that encompasses all the x values of all datasets plotted in this window so far. Note that this default value will override a manual setting of xrange/xmin/xmax in a previous plot to the same window.
It is not allowed to specify xrange and xmax/xmin properties in the same call. If xrange is specified, then simultaneously specifying a conflicting xlog value (i.e. setting xlog to True if xrange contains values <= 0) will lead to an error message.
yrange Set the bounds for the plot's y-axis values. If the resulting range contains elements <= 0, the ylog property will be set to False. 2-element sequence (Python tuple or list) of doubles. <Derive from data>
Calculate the minimal range that encompasses all the y values of all datasets plotted in this window so far. Note that this default value will override a manual setting of yrange/ymin/ymax in a previous plot to the same window.
It is not allowed to specify yrange and ymax/ymin properties in the same call. If yrange is specified, then simultaneously specifying a conflicting ylog value (i.e. setting ylog to True if yrange contains values <= 0) will lead to an error message.
xmin Set a minimum bound for the plot's x-axis value range. double <Derive from data>
Calculate the largest value still smaller than all the x values values of all datasets plotted to this window so far. Note that this default value will override a manual setting of xrange/xmin in a previous plot to the same window, so for a user it only makes sense to provide a manual range minimum via a property for the final plot to a given window.
It is not allowed to specify xrange and xmax/xmin properties in the same call. xmin must not conflict an xlog property values specified in the same plot() command.
xmax Set a maximum bound for the plot's x-axis value range. double <Derive from data>
Calculate the smallest value still larger than all the x values values of all datasets plotted to this window so far. Note that this default value will override a manual setting of xrange/xmax in a previous plot to the same window, so for a user it only makes sense to provide a manual range maximum via a property for the final plot to a given window.
It is not allowed to specify xrange and xmax/xmin properties in the same call. xmax must not conflict with an xlog property value specified in the same plot() command.
ymin Set a minimum bound for the plot's y-axis value range. double <Derive from data>
Calculate the largest value still smaller than all the y values values of all datasets plotted to this window so far. Note that this default value will override a manual setting of yrange/ymin in a previous plot to the same window, so for a user it only makes sense to provide a manual range minimum via a property for the final plot to a given window.
It is not allowed to specify yrange and ymax/ymin properties in the same call. ymin must not conflict with an ylog property value specified in the same plot() command.
ymax Set a maximum bound for the plot's y-axis value range. double <Derive from data>
Calculate the smallest value still larger than all the y values values of all datasets plotted to this window so far. Note that this default value will override a manual setting of yrange/ymax in a previous plot to the same window, so for a user it only makes sense to provide a manual range maximum via a property for the final plot to a given window.
It is not allowed to specify yrange and ymax/ymin properties in the same call. ymax must not conflict with an ylog property value specified in the same plot() command.
xlog Set the x-axis for the plot to use a logarithmic scale. boolean False Trying to set xlog to True yields an error if the new xrange contains values <= 0 (regardless of whether that range was implied by the data, or manually set by the user in the same plot() call using the xrange property).
ylog Set the y-axis for the plot to use a logarithmic scale. boolean False Trying to set ylog to True yields an error if the new yrange contains values <= 0 (regardless of whether that range was implied by the data, or manually set by the user in the same plot() call using the yrange property).
xbase Set the base for the linear and logarithmic tick calculation for the x-axis. double 10.0 xbase >= 1.0
ybase Set the base for the linear and logarithmic tick calculation for the x-axis. double 10.0 ybase >= 1.0
xlabel Set the label to be displayed centered on the outside of the x-axis. string no label
ylabel Set the label to be displayed centered on the outside of the y-axis. string no label
xnumticks Set the number of ticks to be displayed on the x-axis. int 6 xnumticks >= 2
ynumticks Set the number of ticks to be displayed on the y-axis. int 6 ynumticks >= 2
numticks Set the number of ticks to be displayed on the axes. int 6 numticks >= 2
showanimationtoolbar Display an animation toolbar along the bottom of the plot window. boolean <calculated>
If the plot contains a dataset with more than one frame, the animationtoolbar is shown by default.
The animationtoolbar will only be shown if there are datasets with more than 1 frame available.
showpropertypanel Create the plot window with the properties panel showing. boolean False

The available dataset properties for plot() are:

DATASET PROPERTIES FOR plot()
keyword description type default value constraints
value Select which field of the provided HARP product to use as plot value. string By default the first 'sensible' (e.g. not time, latitude, longitude, etc.) variable will be used as plot value. Can only be used when plotting HARP products
name Set the dataset name. This name is how the dataset will be referred to in the Dataset panel selection box. string
  • "Dataset" for lists and numpy array plots.
  • "Spectral Readout" for plots of spectral data.
  • "Reference Spectrum" for plots of reference spectrum records.
  • "Profile <species>" for profile data, where <species> is the value of the "species" field.
After removing leading and trailing whitespace, 'name' must be non-empty. Consecutive datasets with the same name will get a sequence number appended.
lines Draw connecting lines between consecutive data points. boolean True
linewidth Set the width of the lines in the plot, in screen units. double 1.0 linewidth >= 0
stipplepattern Set the stippling pattern for lines, as a 16-bit binary pattern (1 = pixel on, 0 = pixel off). integer 65535 == 0xFFFF == binary 1111 1111 1111 1111 (i.e. solid lines) 0 < stipplepattern <= 65535
points Visualize the data points in the dataset by drawing them as small circles. boolean False
pointsize Set the relative diameter of the data point circles. double 1.0 pointsize >= 0
color Set the color to use for plotting this dataset, in (R,G,B) values. 3-element sequence (Python tuple or list) of doubles. Subsequent plots in the same window will get a color assigned using the following sequence of colors:
  1. (1.0, 0.0, 0.0) red
  2. (0.0, 1.0, 0.0) green
  3. (0.0, 0.0, 1.0) blue
  4. (1.0, 0.0, 1.0) magenta
  5. (0.0, 1.0, 1.0) cyan
  6. (0.7, 0.7, 0.0) poison green
  7. (0.0, 0.7, 0.7) sea blue
  8. (0.7, 0.0, 0.7) deep purple
  9. (0.5, 0.0, 0.0) dark red
  10. (0.0, 0.5, 0.0) dark green
  11. (0.0, 0.0, 0.5) dark blue
0 <= R <= 1.0
0 <= G <= 1.0
0 <= B <= 1.0
opacity Set the opacity (transparency level) of the plotted dataset. A value of 0.0 indicates full transparency. double 0.6 0 < opacity <= 1.0

histogramplot(data, bins)

Draw a histogram plot.

This is a convenience function that creates a histogram in a plot window.

>>> histogramplot(data, bins)

will create a histogramplot where 'data' is the output of the histogram() function and 'bins' is the bins parameter that was used to create the histogram.

Both 'data' and 'bins' should be rank-1 arrays and the array length of 'data' should be one less than the length of 'bins'.

For customizing the plot you can use the same additional options as are available for the plot() function.

wplot(...)

Display a dataset plotted onto an Earth world map.

The wplot() accepts dataset parameters similar to the plot() function. It can also plot basic longitude vs. latitude data as well as HARP products containing groundpixel data or geomap data. All datasets are plotted onto a 2D or 3D Earth world map.

Basic usage:

>>> wplot(longitude, latitude)

will plot the locations using the information from the 'latitude' and 'longitude' arrays and project these onto a world map, in a single plot frame. The type of projection can be chosen by supplying a value for the 'projection' keyword. The latitude/longitude arrays may contain either points or corner coordinates.

>>> wplot(longitude, latitude, data)

will plot the locations using 'data' as color information.

If 'data' is one-dimensional, then the data will be plotted as points or swaths. It will be plotted as points if the latitude/longitude arrays are one-dimensional, and as swaths if latitude/longitude arrays are two-dimensional (in which case the second dimension should capture the corners of the swath)

If 'data' has more than one dimension, then 'data' will be plotted as a grid using the latitude and longitude as axis. Latitude should match the last dimension of 'data' and longitude the second-last dimension. If 'data' is three dimensional, then an animation plot is created with the first dimension being used as time dimension.

>>> wplot(harpproduct)

where 'harpproduct' is an object of type harp.Product (see also the documentation for the HARP Python interface), will display a specific worldmap plot associated with the type of data contained in 'harpproduct'.

>>> wplot(harpproduct, value='variablename')

by using the value parameter you can select which variable from the HARP product should be used to generate the worldmap plot.

The wplot() function also accepts a number of comma-separated optional properties of the form 'property=value'. Their order is arbitrary, but they must always appear after any data arguments to the wplot() function. For example:

>>> wplot(latitudes, longitudes, data, colortable="Ozone", heightfactor=0.4)

Specifying a property multiple times in the same wplot() command is not allowed and will lead to a Syntax Error if attempted.

There are two types of properties: plot properties and dataset properties. A plot property applies 'globally', i.e. plot-wide. If the property is supplied multiple times in consecutive wplot() function calls to the same plot window, the last supplied value will take precedence and override any earlier values. You can also specify dataset properties which will have an effect for each separate dataset plotted to a window. The available plot properties for wplot() are:

PLOT PROPERTIES FOR wplot()
keyword description type default value constraints
window Set the window to plot the dataset in. <wplotwindow handle>
the returned value of a previous wplot() command
create a new window Value should refer to a valid window that has not yet been closed or otherwise destroyed.
windowtitle Set the window title of the plotwindow. string 'VISAN World Plot'  
size Set the initial size of the plot window, in (width, height) pixels. This property only has an effect when specified in the wplot() command that creates the plot window. It is ignored when specified for any subsequent plot into that window. 2-element tuple (800, 494)
(Golden Ratio)
width > 0
height > 0
pos Set the initial position of the plot window, in (x, y) left-upper corner coordinates. 2-element tuple <calculated>
New windows are placed a bit down and to the right with regard to the previously opened window. When there is no further space left, a new window will be created in the top left corner of the screen.
x >= 0
y >= 0
title Set the plot title. string no title
centerlat Set the latitude value of the point at which the view should be centered. double 0.0 -90 <= centerlat <= 90
centerlon Set the longitude value of the point at which the view should be centered. double 0.0 -180 <= centerlon <= 180
zoom Set the zoom level for the view. double 1.0 for 2D projections and 2.5 for the 3D projection. 1.0 <= zoom
projection Set the type of projection to use for the plot string "3D" projection must be one of the following values:
  • "Plate Caree"
  • "Robinson"
  • "Mollweide"
  • "Lambert Cylindrical"
  • "Lambert Azimuthal"
  • "Azimuthal Equidistant"
  • "3D"
With the exception of "3D" these are all 2-dimensional projections of the world sphere. "3D", as the name implies, is a rendering of the dataset onto a sphere.
projectionlat Set the center latitude parameter for the projection. This is only applicable for Azimuthal 2D projections. double 0.0 -90 <= projectionlat <= 90
projectionlon Set the center longitude parameter for the projection. This is only applicable for 2D projections. double 0.0 -180 <= projectionlon <= 180
showanimationtoolbar Display an animation toolbar along the bottom of the plot window. boolean <calculated>
If the plot contains a dataset with more than one frame, the animationtoolbar is shown by default.
The animationtoolbar will only be shown if there are datasets with more than 1 frame available.
showpropertypanel Create the plot window with the properties panel showing. boolean False
showcolorbar Display a color bar along the bottom of the plot panel. boolean <calculated>
If the plot contains a dataset with a color table, the color bar is shown by default.

The available dataset properties for wplot() are:

DATASET PROPERTIES FOR wplot()
keyword description type default value constraints
value Select which field of the provided HARP product to use as plot value. string By default the first 'sensible' (e.g. not time, latitude, longitude, etc.) variable will be used as plot value. Can only be used when plotting HARP products
colortable The color table to associate with the values in dataset.
VISAN will first try to see if the value of this string is equal to one of its built-in predefined color tables: "BlackToWhite", "WhiteToBlack", "GreenToRed", "RedToGreen", "Cloud", "Rainbow", "Ozone", "Blackbody", or "Aerosol".
In all other cases, the string is interpreted as a filename containing a VISAN color table definition. If the filename is not an absolute path specification, VISAN searches for the file in the current directory (from which the script or application was launched).
string Aerosol filename should refer to a valid, existing color table
colorrange Set the minimum/maximum scalar values for scalar mapping of the color table. Scalar values less than the minimum range value are clamped to minimum range value. Scalar values greater than the maximum range value are clamped to maximum range value. 2-element sequence of double <calculated>
The initial value is set to the min/max values of the entire dataset.
colorbartitle Set the title to be used when the colorbar for this data is shown. string no title
numcolorlabels Set the number of value labels to display for the color bar associated with the dataset. int 2 numcolorlabels >= 0
opacity Set the opacity (transparency level) of the plot. A value of 1.0 indicates no transparency. double 0.7 0 < opacity <= 1.0
linewidth Set the width of the Path lines in the plot. double 1.0 linewidth >= 0
pointsize Set the diameter of circles signifying Location points. double 1.0 pointsize >= 0
drawpath Draw a Path between measurement locations for the given dataset. This will only show a black line and won't use color information based on the data. boolean False
drawlocation Use the center locations instead of corner coordinate information to create the plots. This is only applicable when plotting HARP product data. boolean False
heightfactor Set the height factor for a Geomap dataset. This property is only meaningful for "3D" projection type plots. If value > 0 then the data will be visualized using a height proportional (scaled with the heightfactor) to the data value. double 0 heightfactor >= 0
minheightvalue Set a minimum, pre-normalisation, pre-heightfactor-application cutoff value for the mapping of values in a Geomap dataset to heights. This property is only meaningful for "3D" projection type plots with heightfactor > 0. double <calculated>
The minimum value found in the dataset.
maxheightvalue Set a maximum, pre-normalisation, pre-heightfactor-application cutoff value for the mapping of values in a Geomap dataset to heights. This property is only meaningful for "3D" projection type plots with heightfactor > 0. double <calculated>
The maximum value found in the dataset.
deltaradius Set the Radius for the Geomap filter. This property is only meaningful for "3D" projection type plots. This value sets the distance of the visualized data from the unit sphere (i.e. the Earth). double 0.007 deltaradius >= 0

Mathematical functions

All mathematical functions are available inside the visan.math package. To use e.g. the fit() function you can either use from visan.math import fit and then call fit(), or you can directly call visan.math.fit().

visan.math.gammaln(x)

The logarithm of the gamma function ln(Gamma(x)).

This function is not guaranteed to work on imaginary data.

visan.math.gammap(a, x)

The incomplete gamma function P(a,x) (= gamma(a,x) / Gamma(a)).

visan.math.gammaq(a, x)

The incomplete gamma function Q(a,x) = 1 - P(a,x) (= 1 - gamma(a,x) / Gamma(a)).

visan.math.histogram(a, bins, mode='inner')

Create a histogram for a set of values using a specified set of bins.

This function creates a histogram for the values in the array a. The bins are defined by the edge values in the bins array. The values in bins should be stored in ascending order.

If mode is 'inner' then len(bins)-1 bins will be used. If mode is 'outer' then two more bins are added; one for all values below bins[0] and one for the values in a higher then bins[-1].

Both a and bins should be one dimensional arrays.

Example:

>>> visan.math.histogram([2.1, 4.5, 5, 7.8, 2.5, 6.1, 9.9, 5.1, 5.2, 7.2], numpy.arange(11))
numpy.array([0, 2, 0, 1, 3, 1, 2, 0, 1, 0])

visan.math.fit(x, y, sigy=None, error=False)

Perform a linear fit on a range of x and y values.

This function fits a set of data points x, y with individual standard deviations sigy for the y values to a straight line y = a + bx by minimizing chi-square.

If the error parameter is False the function returns only the found values for a and b as a tuple. If error is True then a third tuple item is returned containing a dictionary of error statistics (siga the standard deviation of a, sigb the standard deviation of b, chi2 the value of chi-square, and q the goodness of fit probability).

If sigy is None then no standard deviations are used, q will be 1.0 and the normalization of chi-square is to unit standard deviation for all points.

Example:

>>> a, b, err = visan.math.fit([1.1, 1.95, 3.05], [1, 2.01, 2.95], error=True)

visan.math.lfit(x, y, F, sigy=None, error=False)

Perform a fit on a range of values using a set of basis functions.

This function fits a set of data points x, y with individual standard deviations sigy for the y values to a linear combination of basis functions y = sum(a_i * F_i(x); i = 1..N) minimizing chi-square.

F should be a user provided function F(x) that returns an array where each element is the evaluation of the basis function F_i() at location x.

The function lfit will return an array a with the coefficients for the basis functions F_i().

If the error parameter is False the function returns only the found values for a as an array. If error is True then a tuple is returned containing the array a, the covariance matrix, and the value of chi-square.

If sigy is None then the standard deviations for all y values are set to 1.0.

Example (fit to a second degree polynomial):

>>> def F(x):
...    return numpy.array([1, x, x*x])
>>> a, covar, chi2 = visan.math.lfit([0, 1, 2, 3], [1, 3, 2, 1], F, error=True)
>>> y = numpy.dot(a, F(0.5))

Miscellaneous functions

executescript()

Execute a script.

This routine runs an external python script.

>>> executescript(filename)

runs the script file located at the path indicated by filename and returns to the prompt when the script is finished. If the system is unable to locate the file indicated by filename an execption will be thrown.

When you run a script, VISAN will automatically add the location of your script to the module searchpath (sys.path). This means that if your script uses modules that are located in the same directory as the script file then these modules will automatically be found. When the script is finished VISAN will change the module searchpath back to its original value.

If you want the script to have access to variables that you have already set or if you want to have access to variables that are going to be set by the script, just pass globals() as second parameter:

>>> executescript(filename, globals())

If the script needs to be run as a 'main' script (i.e. as if it was run as an argument to the python executable) and/or requires command line arguments you can use the mainargs keyword. The mainargs keyword should contain a list of command line options (which may be an empty list). For instance, to run a setup.py script to install an external module you could use:

>>> executescript('/home/user/package/setup.py', mainargs = ['install'])

This will have the result that the script is called with the __name__ variable set to '__main__' and sys.argv will have been set to ['/home/user/package/setup.py', 'install']. The current working directory for the script will also be set to the directory of the script (e.g. '/home/user/package').

Note that if a mainargs keyword parameter is provided, the globals parameter to executescript() (if present) will be ignored.

version()

Get the version number of VISAN.

>>> v = version()

returns the version number of the current VISAN release.