VISAN Tutorial

This is a short tutorial that demonstrates some of the functionality that VISAN offers. It will show you how to use BEAT-II to ingest product data, how to visualize this data and how to perform some simple calculations on this data.

Contents

Starting VISAN

We begin by starting VISAN. Depending on the platform you use, you should do the following:

When VISAN is starting up you should see the VISAN splash screen pop up. After the application has fully loaded (this can take some time, especially on older systems) the Main Window of VISAN should appear. We will use the command area in this window to provide our commands to read data, create plots, etc.

[screenshot]

MIPAS Level 2 Ozone profile

We will illustrate the features of VISAN using some MIPAS Level 2 ozone profile data. However, if you want to use VISAN for other types of data, the steps you will have to perform will be very similar to the ones described below.

The first step we will perform is load some MIPAS Level 2 product data into memory. For this we will use the BEAT-II interface that ships with VISAN. All BEAT-II functionality is grouped together in a package named beatl2. This means that when we want to call a BEAT-II function we will have to prefix it with 'beatl2.'. To read data from an instrument product file, we will use the ingest function from BEAT-II. This function expects as first argument a specification of the MIPAS Level 2 product file(s) that you want to ingest and as second parameter a string containing filter options (the kind of filter options that can be provided depends on the type of the product(s) you want to read).

Say that we have stored our MIPAS Level 2 product files in the directory /data/mipasl2 then we can issue the following command in VISAN to ingest ozone profile data:

>>> o3data = beatl2.ingest('/data/mipasl2/MIP_NL__2P*','o3_vmr_min=0')

Note that we use a wildcard in the filename specification. This means that BEAT will ingest all MIPAS Level 2 files from your directory at once. If you have many files then you might consider using an explicit list to specify only the subset of files you want (beatl2.ingest(('file1', 'file2', 'file3'), 'o3_vmr_min=0')).

The filter option that we provided ('o3_vmr_min=0') makes sure that we only ingest positive O3 volume mixing ratio values but, as a nice side effect, it also filters out all invalid O3 vmr values (i.e. values that are nan). You can also provide other/additional filter options to limit data based on e.g. time and geolocation such as latitude_min=...,latitude_max=... or time_min=...,time_max=... (you can find more information about the possible filter options for each of the supported products in the BEAT-II Data Description documentation).

To view the contents of the o3data structure, just print it:

>>> print o3data
                            type: 'MIPAS_NL_L2'
            elements_per_profile: [64 int32]
                            time: [895 double]
                        latitude: [895 double]
                       longitude: [895 double]
                        altitude: [895 double]
                        pressure: [895 double]
                          o3_vmr: [895 double]
                     o3_vmr_unit: 'ppmv'
                    o3_vmr_error: [895 double]
               o3_vmr_error_unit: 'ppmv^2'

As you can see the o3data is a record and you can inspect the contents of individual fields of this record by printing the field. For instance, to view the number of retrieval points for each ingested profile you would do the following:

>>> print o3data.elements_per_profile
[14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 13 14
 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14
 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14]

We can create a plot from the profile data by using the plot function:

>>> plot(o3data)

This will produce a plot window showing you the first profile from all ingested profiles. The vertical axis contains the height in km and the horizontal axis the species concentration. If you press the Animate button at the bottom the plot will start to loop through all profiles.

[screenshot]

You can also pan and zoom your plot by clicking and dragging your right or left mouse button in the plot area.

The property panel on the right was automatically opened. You can open/close this panel by choosing the 'Properties' menu option from the 'View' menu. The 'Data Sets' tab of the property panel shows various attributes for the currently selected data set (this data is taken directly from the BEAT-II record that we passed to the plot function).

Now select the 'Plot' tab in the Properties panel. In this panel you can set various properties such as the plot title and various axes related properties. Lets try giving our plot a different title. In the top field ('Plot Title') enter the text "MIPAS O3 profile". When you press 'enter' you will see that the plot window updates the title at the top of the plot.

[screenshot]

Now close the plot window and go back to the main VISAN window. We will now show the latitude/longitude location for each of the profile points in a worldplot window. Enter the following at the VISAN command prompt:

>>> wplot(o3data)

This will bring up a 3D world showing the location of all profile points (i.e. it shows all profiles at once). By default the data is plotted using a default color table and using default color table ranges.

Just as for the 2D plot you can use the mouse to pan, zoom, and rotate the view.

If you open the property panel for this plot and select the 'Plot' tab you can select between different projections. Click on the drop down box and change the projection from '3D' to 'Lambert Azimuthal'. The plot will now change to a 2D projection of the earth. Then change the value in the 'Zoom' field to 1.0 to show the full globe again.

[screenshot]

As a final excercise we will do some calculations on the time values that are inside the o3data record. The time values in a BEAT-II record are always given in 'seconds since 01-JAN-2000 00:00:00.000000'. You can use the time_to_string function from the coda package (this is the BEAT layer 1 interface) to display a time value as a string. For instance:

>>> print o3data.time[0]
80824943.5187
>>> print coda.time_to_string(o3data.time[0])
2002-07-24 11:22:23.518737

Say that we want to plot the tangent altitude of each profile point against its time, but we want to represent the time in minutes relative to the first profile point. We can then create a new array of time values as follows:

>>> t = (o3data.time - o3data.time[0]) / 60.0

Now we can use the plot function again to create the plot. We will provide some additional options to the plot command to immediately get the plot we want:

>>> plot(t, o3data.altitude, points=True, lines=False,
...     xlabel="time [minutes]", ylabel="altitude\n[km]",
...     ymin=0, ymax=80, color=(0.6,0.3,0),
...     title="MIPAS altitudes for all profile points")
[screenshot]

This concludes this short tutorial for the MIPAS Level 2 data. For more information about the plot functions and other VISAN functionality please refer to the VISAN User Manual and Reference Manual. The BEAT functionality of VISAN is further described in the CODA Python and BEAT-II Python documentation.

Other products types

If you don't have any MIPAS Level 2 products, you can just as easily follow the steps above with any of the other products that are supported by BEAT. Just look in the BEAT-II Data Description documentation to find the list of appropriate filter options that you can provide to the beatl2.ingest() function. Depending on the data you retrieve, you can either use plot() and/or wplot() to display its data. Some BEAT-II record data, such as the profile data coming from the MIPAS Level 2 product, can be used as input to both plotting functions.

The wplot function, for instance, was primarily created to plot level 2 data from nadir looking instruments such as SCIAMACHY or GOME and for level 3/4 data (global assimilated datasets). So if you use the BEAT-II ingest function to read such data, you can use the ingested record as input to the wplot function to see a colored view of the measured values. The picture below shows an example of what you would get when you use GOME Level 4 data (available from the GOME Fast Delivery website).

[screenshot]

Example scripts

For most product types VISAN also comes with an example script that shows you how to ingest data from such a product and how to create a plot from it. The example scripts can be found in the examples subdirectory of your VISAN installation. You can execute a script by chosing the 'Load and Execute Script...' option from the 'File' menu of the main window.

Copyright © 2002-2010 s[&]t, The Netherlands.