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
  • histogramplot
  • wplot
• Mathematical functions
  • visan.math.gammaln
  • visan.math.gammap
  • visan.math.gammaq
  • visan.math.histogram
  • visan.math.fit
  • visan.math.lfit
• Miscellaneous functions
  • executescript
  • version

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:

The available dataset properties for plot() are:

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:

The available dataset properties for wplot() are:

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.