TOVS Path-P IDL Tools Tutorial

Introduction

NSIDC developed a number of IDL programs to browse and visualize TOVS Pathfinder Path-P Daily and Monthly Polar Gridded Atmospheric Parameters data files. The IDL tools described in this tutorial are available via HTTPS, along with the aforementioned data set, in the /tools/ directory. For instructions on installing these tools, see the Getting Started section below. Installing and running these IDL tools allows the user to perform the following functions (this Tutorial contains examples of each):

Listing a table of contents, including dates, daily variables and ancillary data
Displaying a color image of any variable and date
Displaying a color animation of any variable and a range of dates
Displaying a scatter plot of any two variables for a given date
Displaying a time-series plot of any (column,row) coordinate for any variable and range of dates
Displaying a table of general statistics (minimum, maximum, average, standard deviation) for any variable and range of dates
Extracting, saving, and restoring a 3-dimensional array of data and its associated metadata for any variable and range of dates
Conversion routines for (latitude,longitude) to/from (column,row) coordinates

The IDL tools were developed at NSIDC with the exception of colorbar.pro, which is used for the legends on most of the color graphics displays. The tool colorbar.pro is included here with the kind permission of its author, Dr. David Fanning.

Getting started

These IDL tools have been written for use with IDL 6.0 or later and have been tested on Unix and Windows machines.

The IDL tools require that the TOVS Pathfinder Path-P Daily and Monthly Polar Gridded Atmospheric Parameters data files to be organized in a specific way on your disk. All the data files must be placed under the same base directory. The ancillary data files (tpp_n100_9999999_ancil.hdf for the Northern Hemisphere and tpp_s100_9999999_ancil.hdf for the Southern Hemisphere) must be in the base directory, while the daily data files must be in yearly subdirectories under the base directory. The directory name of each yearly subdirectory must be the 4-digit year. The easiest way to ensure that your directory is set up properly is to download the daily data tar files to the base directory and untar them from there. The yearly subdirectories will be created automatically.

Example:

Unix systems: This example assumes that the data files will be stored in your home directory under a subdirectory named tovs, for example, in /usr/me/tovs (Note: This location is arbitrary; the data files can be stored anywhere in your file system that there is sufficient space). In this example, the ancillary data files (tpp_n100_9999999_ancil.hdf and tpp_s100_9999999_ancil.hdf) would be placed in /usr/me/tovs. The daily data files would be placed in the subdirectories /usr/me/tovs/1979 for 1979 data, /usr/me/tovs/1980 for 1980 data, and so on. One way of setting this up is to download the daily data tar files to /usr/me/tovs and untar them from there to create the subdirectories automatically. Note: Files other than daily data files should not be put in the directories with the daily data files.
Windows: This example assumes that the data files will be stored under the directory b:\tovs (Note: This location is arbitrary; the data files can be stored anywhere in your file system that there is sufficient space). In this example, the ancillary data files (tpp_n100_9999999_ancil.hdf and tpp_s100_9999999_ancil.hdf) would be placed in b:\tovs. The daily data files would be placed in the subdirectories b:\tovs\1979 for 1979 data, b:\tovs\1980 for 1980 data, and so on. One way of setting up the correct directory structure is to download the tar files to b:\tovs and untar them from there to create the subdirectories automatically. Note: Files other than daily data files should not be put in the directories with the daily data files.

To download and run the tools from the TOVS Path-P HTTPS site, please perform the following steps. Implementation of each step will vary depending on your operating system and shell.

Download tools from the TOVS Path-P FTP site
Add the path to the tools to your IDL path
Set the startup file
Pick a fixed-width font for your output log
Restart IDL
Begin using the tools with the tutorial

1. Download tools from the TOVS Path-P site

If downloading in bulk, follow the general NSIDC instructions for bulk download via HTTPS.

Note: You must download all the files to ensure that the tools will work properly.

2. Add the path to the tools to your IDL path

Note: Be sure to add the new path without eliminating any existing paths.

Unix systems: The exact syntax will depend on your shell. On systems using flavors of C shell, an example of the command would be the following:

setenv IDL_PATH /usr/me/tovs/IDL_tools\:$IDL_PATH

Note: The pathname /usr/me/tovs/IDL_tools is only used as an example. If you get an error message similar to IDL_PATH: undefined variable, you need to run the idl_setup script. If you do not know how to run this script, consult your system administrator.

Windows: Start IDL and add the directory name where you put the tools to the list of default paths using the pull-down menus: File->Preferences->Path.

3. Set the startup file

There are two different version of the startup file. A Unix version called unixstrt.pro and a Windows version called winstrt.pro. When you use the startup file, IDL will compile each of the tool's programs in the correct order and will set the device visual so that the display colors behave correctly. The tools were built assuming that PseudoColor is used on Unix systems and decomposed color is turned off on Windows systems. Unexpected results will occur on the color displays if you run the tools using TrueColor. If you use a customized startup file, you may wish to merge the startup file provided with your own customizations.

Unix systems: The exact syntax will depend on your shell. On systems using flavors of C shell, an example of the command would be the following:

setenv IDL_STARTUP /usr/me/tovs/IDL_tools/unixstrt.pro

Note: The pathname /usr/me/tovs/IDL_tools is only used as an example.

Windows: Start IDL and change the startup file to the full path name on your disk using the pull-down menus: File->Preferences->Startup. For example, if you put the tools in b:\tovs\IDL_tools, then you would enter b:\tovs\IDL_tools\winstrt.pro.

4. Pick a fixed-width font for your output log

Some of the tools display text output in the IDL window. The output will be easier to read if you are using a fixed-width font such as Courier or Courier New.

Unix systems: This will depend on the window manager you are using. One way for users with xterm to do this is to add the following line to your .Xdefaults file:

xterm*font: -adobe-courier-*-o-*-*-20-*-*-*-*-*-*-*

Windows: Start IDL and change the font for the output log to Courier using the pull-down menus: File->Preferences->Fonts. Select Output Log and then Courier font.

5. Restart IDL

For these changes to take affect, you must restart IDL. After restarting, your display should look similar to the following:

IDL Version 6.x. Research Systems, Inc. Installation number: xxxx. Licensed for use by: your company/institution

For basic information, enter IDLInfo at the IDL> prompt. It should print the following:

% Compiled module: COLORBAR.
% Compiled module: BLANK_LEGEND.
% Compiled module: MAKE_LEGEND.
% Compiled module: PAINT_LEGEND.
% Compiled module: SNOWICE_LEGEND.
% Compiled module: OCEAN_LEGEND.
% Compiled module: SSMI_CONVERT.
% Compiled module: SSMI_INVERSE.
% Compiled module: EASE_CONVERT.
% Compiled module: EASE_INVERSE.
% Compiled module: PPPU_ADD_SDS.
% Compiled module: PPPU_FILES.
% Compiled module: PPPU_GET_SDS_DESCRIPTIONS.
% Compiled module: PPPU_IS_ANCILLARY_SDS.
% Compiled module: PPPU_YYYYDOY_TO_JULDAY.
% Compiled module: PPP_READ.
% Compiled module: PPP_TOC.
% Compiled module: PPP_EXTRACT.
% Compiled module: PPP_STATS.
% Compiled module: PPP_PLATFORM.
% Compiled module: PPP_PLOT.
% Compiled module: PPP_PLOT_XPARAMS.
% Compiled module: PPP_COMPARE.
% Compiled module: PPP_SHOW.
% Compiled module: PPP_ANIMATE.
% Compiled module: PPP_SAVE.
% Compiled module: PPP_RESTORE.
% Compiled module: PLAY_GIF.
% Compiled module: PPP_PLATFORM

The Polar Pathfinder P-cube/TOVS IDL access routines are now installed. Please refer to index.html in the HTML documentation, for more information about these tools, including extended help documentation.

Select Platform: Enter 1 for P-cube Enter 2 for TOVS Northern Hemisphere Path-P Daily Enter 3 for TOVS Northern Hemisphere Path-P Monthly Enter 4 for TOVS Southern Hemisphere Path-P Daily :

The prompt at the end of the installation requires you to select the data you want to visualize. For this tutorial and data set, you will only be concerned with modes 2, 3, and 4 (P-cube is a different data set not discussed in this tutorial). Note: You can use the procedure ppp_platform at any time to switch data sets.

If you see compilation errors during startup, the first thing to check is if you have overwritten your current IDL_PATH (instead of appending the IDL tools directory to your existing path, thereby causing IDL to lose track of standard IDL functions). The way to check this is to print the value of IDL_PATH by printing the system variable !path and to confirm that the output looks similar to the following:

IDL> print, !path /usr/me/tovs/IDL_tools:+/usr/local/rsi/idl5.1/idl_5.1/lib:+/usr/local/rsi/idl5.1/idl_5.1/examples

And not like this:

IDL> print, !path /usr/me/tovs/IDL_tools

If you did overwrite your IDL_PATH, you must start a new window to get the original path back before re-executing the setenv commands above.

6. Begin using the tools with the tutorial.

Please refer to the Extended Help documentation and the Tutorial for examples and suggestions on how to run the tools.

Tutorial

If you have not already set up your copy of IDL to run the TOVS Path-P IDL tools, please follow the directions in the Getting Started section above before attempting the tutorial.

This tutorial assumes that you are familiar with the IDL command line and array and structure terminology. The first step you need to take is to set the working directory to the root or base data directory. To do this, use the IDL cd procedure by typing the following at the IDL command prompt:

IDL> cd, 'mydir/tovs'

Where mydir is the full or relative pathname of the base directory where your TOVS Path-P data resides.

This tutorial is divided into four general categories of routines. We recommend that the user proceed chronologically as follows:

Displaying general information and statistics about the data files
Color displays
Plots
Extracting, saving, and retrieving 3-D time-series

Tutorial 1: Displaying general information and statistics about the data files

This section of the tutorial explains how to extract a table of contents for the TOVS Path-P files and explains how to extract a table of statistics for a specific parameter and range of dates. You will learn how to use the following:

PPP_TOC - Displays a table of contents of TOVS Path-P files
PPP_STATS - Displays statistics for one parameter and range of dates

`PPP_TOC` - Displaying a table of contents

The first step in browsing the TOVS Path-P data is to display a table of contents using the IDL procedure, PPP_TOC. This procedure has two required arguments:

sds_desc: Returns an array of structures that contain metadata pertaining to each HDF Scientific Data Set (SDS) included in the data. Metadata will include the SDS name, a longer descriptive label, the units, and the fill value used for this SDS.
dates: Returns an array of dates, one for each daily file included in your TOVS Path-P data directory.

PPP_TOC will traverse the current directory structure, looking for all TOVS Path-P files contained there and will display an informational message that summarizes what it has found. The list of parameter names, returned to you in the array sds_desc.name, is the list of strings that will be considered valid input values to all other routines that accept an argument or keyword called SDS_NAME. The list of dates, returned to you in the dates array, can be used (or subsetted for a particular range of dates) in all other routines that accept an argument called DATES.

Note: PPP_TOC splits the parameter information into two groups: those parameters that change over time and are included in each daily file and those parameters that are static and are included only once in the ancillary data file.

Please refer to the Extended Help documentation for details on the other keywords to PPP_TOC.

`PPP_STATS` - Displaying statistics for one parameter and range of dates

Now that you know which parameters are included in the TOVS Path-P files, you may want to use PPP_STATS to extract some statistics for a given parameter and range of dates. PPP_STATS has one required argument and a number of keywords for flexibility. The required argument is sds_name, which is a string that you select from the parameter listing you just displayed with PPP_TOC.

PPP_STATS also accepts keywords for a date range (START_DATE and END_DATE) or an array of specific dates (DATES). Any dates entered as keywords in this way can be either integers or strings of the form yyyyddd (4-digit year and 3-digit day of year). Other functions that behave similarly are PPP_ANIMATE, PPP_EXTRACT, and PPP_PLOT, which will be covered later in another section of the tutorial. These keywords are not required arguments, because PPP_STATS can also be used to display statistics for the ancillary parameters which are static data that have no associated dates.

Tutorial 2: Color displays of SDS data from TOVS Path-P files

This section of the tutorial explains how to display a color image of a specific parameter and date and explains how to display a color animation of a specific parameter for a range of dates. You will learn how to use the following IDL procedures:

PPP_SHOW - Displays a color image of one parameter for a given date
PPP_ANIMATE - Displays an animated series of data for a range of dates

`PPP_SHOW` - Displaying data for one parameter on a given date

To display a color image of a specific parameter for a given date with map and graticule overlays use PPP_SHOW, which is similar to PPP_STATS in that it only has one required argument, sds_name, one of the strings that you select from the parameter listing from PPP_TOC. You can specify the date of the file to read by using the DATE keyword (either a string or integer of the form yyyyddd). Once again, the DATEkeyword is not required because you might wish to display one of the static, ancillary parameters.

PPP_SHOW accepts a number of other keywords that allow you to set the displayed label or legend title, force a new window to be opened, or to return the actual data array or its associated metadata in named variables. Please refer to the Extended Help documentation for details on the other keywords to PPP_SHOW.

`PPP_ANIMATE` - Displaying an animated series of data for a range of dates

Now that you are familiar with the way temperature data can be displayed for a single day, you can use PPP_ANIMATE to extract a 3-D time-series of a given parameter and a range of dates. Like PPP_STATSand PPP_SHOW, PPP_ANIMATE has sds_name as one required argument and a number of keywords for flexibility.

Like PPP_STATS, PPP_ANIMATE accepts keywords for a date range (START_DATE and END_DATE) or an array of dates (DATES). The defaults are the beginning and end of all TOVS Path-P data found under the current directory, however, since this routine is very memory intensive, it is recommended that you limit the dates that you animate according to your system's memory. For example, a movie of only 100 days would require 670 columns x 670 rows x 100 days which is almost 45 Mb of memory. Since each user's system is different, there are no safeguards built into PPP_ANIMATE to limit the number of dates you may include; so use this routine with caution.

Tutorial 3: X-Y plots of SDS data in TOVS Path-P files

This section of the tutorial explains how to display a time-series plot of the data value for one pixel (column,row) of a specific sds_name, how to convert between (column,row) and (latitude,longitude) coordinates, and how to display a scatter plot of two sds_names for a given date. You will learn how to use the following IDL routines:

EASE_CONVERT - Converts from (lat,lon) to (column,row) coordinates.
EASE_INVERSE - Converts from (column,row) to (lat,lon) coordinates.
PPP_PLOT - Plots a time-series of SDS data from a given pixel.
PPP_COMPARE - Makes a scatter plot of two SDS arrays for a given date.

`EASE_CONVERT` - Converting (lat,lon) to (col,row) coordinates and
`EASE_INVERSE` - Converting (col,row) to (lat,lon) coordinates

The IDL tools include coordinate conversion routines for converting between (latitude,longitude) and (column,row) coordinates. Both routines, EASE_CONVERT and EASE_INVERSE, are functions requiring five input arguments. The function result will be 0 for a successful return or -1 in the event of an error such as an unknown grid name or if the input coordinates are not on the input grid. The first argument is always the grid name.

Please refer to the Extended Help documentation for complete details on EASE_CONVERT and EASE_INVERSE.

`PPP_PLOT` - Plotting a time-series of SDS data from a given pixel

Now that you know how to determine the particular pixel coordinates for a given (latitude,longitude), you can use PPP_PLOT to extract data values for that pixel and display a time-series plot for a range of dates. PPP_PLOT has three required arguments: sds_name and the column and row coordinates to extract. It also accepts a number of specific keywords and makes use of IDL's keyword inheritance capability, by accepting and passing along any keywords that are valid for IDL's PLOT procedure.

Like PPP_STATS and PPP_ANIMATE, PPP_PLOT accepts keywords for a date range (START_DATE and END_DATE) or an array of dates (DATES). The defaults are the beginning and end of all data found under the current directory. Please refer to the Extended Help documentation for details on the other keywords to PPP_PLOT.

`PPP_COMPARE` - Making a scatter plot of two SDS arrays for a given date

Another plot display is the scatter plot produced by PPP_COMPARE. PPP_COMPARE has three required arguments: the sds_name to plot on the X-axis, the sds_name to plot on the Y-axis, and the date. Like PPP_PLOT, it makes use of IDL's keyword inheritance capability by accepting and passing along any keywords that are valid for IDL's PLOT procedure. It also accepts the CURSOR keyword for interactive mouse behavior.

You can use any keywords to PPP_COMPARE that would normally be accepted by PLOT to customize the plot being displayed, for example, you can shorten the strings used for XTITLE or YTITLE.

Please refer to the Extended Help documentation for details on the other keywords to PPP_COMPARE.

Tutorial 4: Extracting, saving, and restoring 3-D time-series

This section of the tutorial explains various methods for extracting 3-D time-series of data from the HDF files and explains how to save and restore these data for future analysis. You will learn how to use the following IDL routines:

PPP_EXTRACT - Extracts a 3-D slice of data and associated metadata from the HDF files.
PPP_SAVE - Saves a 3-D slice and metadata to an external file, for analysis at a later time.
PPP_RESTORE - Restores a previously saved 3-D slice and metadata from an external file.

`PPP_EXTRACT` - Extracting a 3-D slice of data and associated metadata from the HDF files

You can use PPP_EXTRACT to read a 3-D slice of TOVS Path-P data for a given SDS and range of dates. PPP_EXTRACT is a function with two required arguments: a named variable which will be returned with the extracted data and the sds_name to extract. Like PPP_STATS, PPP_ANIMATE, and PPP_PLOT, it accepts the DATES keyword or a range of dates bounded by START_DATE and END_DATE. It also accepts keywords for two additional portions of metadata from the HDF files: LABELS designates a named variable that will be returned with a string array of dates for each layer of the 3-D data and SDS_INFOdesignates a named variable that will be returned with a structure containing the SDS metadata. Please refer to the Extended Help documentation for details on the other keywords to PPP_EXTRACT.

`PPP_SAVE` and `PPP_RESTORE` - Saving and restoring a 3-D slice and metadata to/from an external file

You can use PPP_SAVE and PPP_RESTORE to write/restore the data and metadata from PPP_EXTRACT to/from an external file for use in other IDL sessions. Both routines have four required arguments: the dataarray, the SDS_INFO structure, a string array of date labels (one for each date layer in the data array), and the name of the external file. Please refer to the Extended Help documentation for details on using PPP_SAVE and PPP_RESTORE.

Extended help

The content for this page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type the following at the IDL command prompt:

IDL> ? mk_html_help

List of routines

COLORBAR
EASE_CONVERT
EASE_INVERSE
PLAY_GIF
PPPU_ADD_SDS
PPPU_FILES
PPPU_GET_SDS_DESCRIPTIONS
PPPU_IS_ANCILLARY_SDS
PPPU_YYYYDOY_TO_JULDAY
PPP_ANIMATE
PPP_COMPARE
PPP_EXTRACT
PPP_PLATFORM
PPP_PLOT
PPP_PLOT_XPARAMS
PPP_READ
PPP_RESTORE
PPP_SAVE
PPP_SHOW
PPP_STATS
PPP_TOC
SSMI_CONVERT
SSMI_INVERSE

Routine descriptions

`COLORBAR`

    NAME:
      COLORBAR
   
    PURPOSE:
          The purpose of this routine is to add a color bar to the current
          graphics window.
   
    CATEGORY:
          Graphics, Widgets.
   
    CALLING SEQUENCE:
          COLORBAR
   
    INPUTS:
          None.
   
    KEYWORD PARAMETERS:
   
          BOTTOM: The lowest color index of the colors to be loaded in
                    the bar.
   
          CHARSIZE: The character size of the color bar annotations. Default is 1.0.
   
          COLOR:    The color index of the bar outline and characters. Default
                    is ncolors - 1 + bottom.
   
          DIVISIONS: The number of divisions to divide the bar into. There will
                    be (divisions + 1) annotations. The default is 2.
   
          FORMAT:   The format of the bar annotations. Default is '(F6.2)'.
   
          MAX:      The maximum data value for the bar annotation. Default is
                    NCOLORS-1.
   
          MIN:      The minimum data value for the bar annotation. Default is 0.
   
          NCOLORS:  This is the number of colors in the color bar.
   
          POSITION: A four-element array of normalized coordinates in the same
                    form as the POSITION keyword on a plot. Default is
                    [0.88, 0.15, 0.95, 0.95] for a vertical bar and
                    [0.15, 0.88, 0.95, 0.95] for a horizontal bar.
   
          PSCOLOR:  This keyword is only applied if the output is being sent to
                    a PostScript file. It indicates that the PostScript device
                    is configured for color output. If this keyword is set, then
                    the annotation is drawn in the color specified by the COLOR
                    keyword. If the keyword is not set, the annotation is drawn
                    in the color specified by the !P.COLOR system variable
                    (usually this will be the color black). In general, this
                    gives better looking output on non-color or gray-scale
                    printers. If you are not specifically setting the annotation
                    color (with the COLOR keyword), it will probably
                  be better NOT to set this keyword either, even if you  
                    are outputting to a color PostScript printer.
   
          RIGHT:    This puts the labels on the right-hand side of a vertical
                    color bar. It applies only to vertical color bars.
   
          TITLE:    This is title for the color bar. The default is to have
                    no title.
   
          TOP:      This puts the labels on top of the bar rather than under it.
                    The keyword only applies if a horizontal color bar is rendered.
   
          VERTICAL: Setting this keyword give a vertical color bar. The default
                    is a horizontal color bar.
   
    COMMON BLOCKS:
          None.
   
    SIDE EFFECTS:
          Color bar is drawn in the current graphics window.
   
    RESTRICTIONS:
          The number of colors available on the display device (not the
          PostScript device) is used unless the NCOLORS keyword is used.
   
    EXAMPLE:
          To display a horizontal color bar above a contour plot, type:
   
          LOADCT, 5, NCOLORS=100
          CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
             C_COLORS=INDGEN(25)*4, NLEVELS=25
          COLORBAR, NCOLORS=100
   
    MODIFICATION HISTORY:
          Written by: David Fanning, 10 JUNE 96.
          10/27/96: Added the ability to send output to PostScript. DWF
          11/4/96: Substantially rewritten to go to screen or PostScript
              file without having to know much about the PostScript device
              or even what the current graphics device is. DWF
          1/27/97: Added the RIGHT and TOP keywords. Also modified the
               way the TITLE keyword works. DWF
          7/15/97: Fixed a problem some machines have with plots that have
               no valid data range in them. DWF

(See colorbar.pro in your IDL TOVS Path-P tools directory.)

`EASE_CONVERT`

 NAME:
	ease_convert

 PURPOSE:
	Use a spherical earth model to convert geographic coordinates to
	azimuthal equal-area or equal-area cylindrical grid coordinates
       for various EASE-Grids.

 CATEGORY:
	Grid coordinate conversion

 CALLING SEQUENCE:
       status = ease_convert ( grid, lat, lon, r, s)

 INPUTS:
       grid: projection name 
             SSM/I Polar Pathfinder: [NSM][lh]
                (where l="low" res (25km), h="high" res (12.5km))
             AVHRR Polar Pathfinder: [NS]a{1,5,25}
                (where 1=1.25 km res, 5=5 km res, 25=25 km res)
             TOVS-P Polar Pathfinder: NpathP (100km res)
             AARI sea ice: AARI (12.5 km res)
       lat, lon - geo. coords. (decimal degrees)

 OUTPUTS:
	r, s - column, row coordinates

 RESULT:
	status = 0 indicates normal successful completion
		-1 indicates error status (point not on grid, unknown
                  projection)

 EXAMPLE:
       status = ease_convert ('Nl',90.,0.,col,row)

       status will be 0, and the returned col, row will be 360.0, 360.0

NOTES:

Please see All About EASE-Grid and Summary of NOAA/NASA Polar Pathfinder Grid Relationships.

(See easeconv.pro n your IDL TOVS Path-P tools directory.)

`EASE_INVERSE`

 NAME:
	ease_inverse

 PURPOSE:
	Use a spherical earth model to convert azimuthal equal-area 
       or equal-area cylindrical grid coordinates to geographic
       coordinates for various EASE-Grids

 CATEGORY:
	Grid coordinate conversion

 CALLING SEQUENCE:
       status = ease_inverse ( grid, r, s, lat, lon)

 INPUTS:
       grid: projection name 
             SSM/I Polar Pathfinder: [NSM][lh]
                (where l="low" res (25km), h="high" res (12.5km))
             AVHRR Polar Pathfinder: [NS]a{1,5,25}
                (where 1=1.25 km res, 5=5 km res, 25=25 km res)
             TOVS-P Polar Pathfinder: NpathP (100km res)
             AARI sea ice: AARI (12.5 km res)
	r, s - column, row coordinates

 OUTPUTS:
       lat, lon - geo. coords. (decimal degrees)

 RESULT:
	status = 0 indicates normal successful completion
		-1 indicates error status (point not on grid)

 EXAMPLE:
       status = ease_inverse ('Nl',360.0, 360.0, lat, lon)

       status will be 0, and the returned lat, lon will be 90.0, 0.0

(See easeconv.pro in your IDL TOVS Path-P tools directory.)

`PLAY_GIF`

 NAME:
	play_gif

 PURPOSE:
	Play a gif animation using xinteranimate.

 CATEGORY:
	Graphics animation.

 CALLING SEQUENCE:
	PLAY_GIF, gif_filename

 INPUTS:
	gif_filename: the full pathname of the gif animation file.
                     If gif_filename is not provided, then
                     PICKFILE is called to allow the user
                     to select a file interactively.

 KEYWORDS:
	GROUP: the widget group of caller.

       DIR: the initial directory in which to select; the
	     directory selected from on return.
       FIRST: the first frame number of the animation to play.
              The default is 0.
       COUNT: the number of frames to play; the default is 50;
              0 means play all the frames remaining in the file
              after FIRST.
       NOREMAP: don't remap palette even if !D.N_COLORS is less
                than 256.

 RESTRICTIONS:
       This procedure requires IDL 5 or higher because it uses
       the /MULTIPLE keyword to READ_GIF which wasn't introduced until
       IDL 5.

 SIDE EFFECTS:
       PICKFILE is called if no gif_filename is provided.
       If !D.N_COLORS is less than or equal to 256 and noremap is
          not set, then a dummy window is opened temporarily to set
          the "true" value of !D.N_COLORS, which is then copied to
          n_colors, and then the window is deleted.
       If !D.N_COLORS LT 256 and noremap is not set, then the palette
          is remapped to consist of !D.N_COLORS colors.
	XINTERANIMATE is called to display the animation. 

 EXAMPLE:
       To display the first 50 frames of the gif animation file
       nor_14_bcktmp_animation.gif, type:

	PLAY_GIF, 'nor_14_bcktmp_animation.gif'

       To display 35 frames starting at frame number 100 of the gif
       animation file bar_14_albd_animation.gif without remapping of
       the palette in an 8-bit color environment, type:

	PLAY_GIF, 'bar_14_albd_animation.gif', FIRST=100, COUNT=35, $
					       /NOREMAP

(See playgif.pro in your IDL TOVS Path-P tools directory.)