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.

  1. Download tools from the TOVS Path-P FTP site
  2. Add the path to the tools to your IDL path
  3. Set the startup file
  4. Pick a fixed-width font for your output log
  5. Restart IDL
  6. 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:

  1. Displaying general information and statistics about the data files
  2. Color displays
  3. Plots
  4. 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:

  1. 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.
  2. 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_ANIMATEPPP_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_SHOWPPP_ANIMATE has sds_name as one required argument and a number of keywords for flexibility.

Like PPP_STATSPPP_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_ANIMATEPPP_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_STATSPPP_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.)


PPPU_ADD_SDS

 NAME:
       PPPU_ADD_SDS

 PURPOSE:
       Adds a new SDS_INFO structure to the array of structures so far.

 CALLING SEQUENCE:
       pppu_add_sds, num_sds, sds_descriptions, name, label, unit,
                     layer_num, fill_value, calibration_factor,
                     uncalibrated_offset

 INPUTS:
       num_sds: the current number of SDS descriptions
       sds_descriptions: the array of SDS_INFO descriptions
       name: the string name of the new SDS
       label: the string label of the new SDS
       unit: the string unit of the new SDS
       layer_num: the integer layer number of the new SDS
         This is usually 0, but may be positive if/when the
         SDS is actually stored as a 3-D array in the HDF file
       fill_value: the SDS fill_value
       calibration_factor: the SDS calibration factor
       uncalibrated_offset: the SDS uncalibrated offset

 OUTPUTS:
       num_sds: the incremented number of SDS descriptions
       sds_descriptions: the array of SDS_INFO descriptions, with
          a new SDS_INFO structure appended to it

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


PPPU_FILES

 NAME:
       pppu_files

 PURPOSE:
       Searches directories for a list of P-cube/TOVS files

 CATEGORY:
	P-cube/TOVS utilities

 CALLING SEQUENCE:
       list=pppu_files(directory)

 INPUTS:
       directory: base directory with P-cube/TOVS files.  This directory
          and 4-digit year subdirectories will be searched for files.

 GLOBAL VARIABLES:
       platform_index: 1 - use P-cube data
                       2 - use TOVS Northern Hemisphere Path-P Daily data
                       3 - use TOVS Northern Hemisphere Path-P Monthly data 
                       4 - use TOVS Southern Hemisphere Path-P Daily data

 KEYWORDS:
       ANCILLARY: set this keyword to return the name of the ancillary
          data file 
       COUNT: number of files found. 
       DATES: list of dates to find daily files for.  Default is all
          files in year subdirectories.  (ignored if ANCILLARY is set)
       END_DATE: if entered, the date to stop extracting.  
              Default is end of all P-cube/TOVS files found.
              (ignored if ANCILLARY is set)
       LABELS: string array of dates of the files found and extracted
              from 
       START_DATE: if entered, the date to start extracting.  
              Default is beginning of all P-cube/TOVS files found.
              (ignored if ANCILLARY is set)

 RESULT:
       A sorted list of files found, or -1 if none were found.

 EXAMPLE:
       list=pppu_files('.')

       Returns a sorted list of all P-cube/TOVS files found in 4-digit year
       subdirectories of ./

 NOTES:
       P-cube/TOVS files are HDF files with the following characteristics:
       1) All files are assumed to be in (4-digit) year 
           subdirectories of the same base directory
       2) File naming convention is dir/yyyy/ppp_n100_yyyyddd_daily.v0
          for P-cube files and dir/yyyy/tpp_Nss_h100_yyyyddd_daily[monthly].vx for
          TOVS files.
       3) The date in the filename is assumed to be correct
       4) There is exactly 1 file per date
       5) All files are assumed to contain the same HDF
          structure.  It is assumed that they all contain
          the same, fixed set of SDSs (Scientific Data Sets)
       6) A single ancillary data file will be assumed to be in dir.

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


PPPU_GET_SDS_DESCRIPTIONS

 NAME:
       PPPU_GET_SDS_DESCRIPTIONS

 PURPOSE:
       Retrieve information for all SDS's in this file

 CALLING SEQUENCE:
       desc = pppu_get_sds_descriptions(filename)
       
 INPUTS:
       filename: filename string from which the SDS descriptions
         will be retrieved

 GLOBAL VARIABLES:
       platform_index: 1 - use P-cube data
                       2 - use TOVS Northern Hemisphere Path-P Daily data
                       3 - use TOVS Northern Hemisphere Path-P Monthly data 
                       4 - use TOVS Southern Hemisphere Path-P Daily data

 KEYWORDS:
       COUNT: the number of SDS_INFO records returned
           
 RESULT:
       Returns an array of SDS_INFO records, one for each SDS in
       this file, or -1 if no records were found.

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


PPPU_IS_ANCILLARY_SDS

 NAME:
       PPPU_IS_ANCILLARY_SDS

 PURPOSE:
       Determine whether sds_name is ancillary data

 CALLING SEQUENCE:
       status=pppu_is_ancillary_sds(sds_name)

 INPUTS:
       sds_name: name of sds to examine

 RESULT: 1 if sds_name is ancillary data, 0 otherwise

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


PPPU_YYYYDOY_TO_JULDAY

 NAME:
       PPPU_YYYYDOY_TO_JULDAY

 PURPOSE:
       Convert year, day of year string to Julian day

 CALLING SEQUENCE:
       status=pppu_yyyydoy_to_julday(yyyydoy)

 INPUTS:
       yyyydoy: string date

 RESULT: the Julian day corresponding to yyyydoy
         or -1 in case of error

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


PPP_ANIMATE

 NAME:
	ppp_animate

 PURPOSE:
	Extracts and animates a time-series array of SDS data of a 
       given type and list of dates (see NOTES for warning about memory).

 CATEGORY:
	HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       ppp_animate, sds_name

 INPUTS:
       sds_name: the string SDS name for this data, (will be used
          to determine display range, colors, etc)

 OUTPUTS:
       labels: string array of labels, 1 for each frame of data

 KEYWORDS:
       DATA: a named variable returned with the requested data array
       DATES: integer or string array of dates [yyyydoy,yyyydoy,...]
          Default is dates of 1st 10 P-cube/TOVS files found.  
       DIRECTORY: base directory with P-cube/TOVS files.  4-digit year
          subdirectories will be searched for P-cube/TOVS files.
          Default is ./
       END_DATE: if entered, the date to stop extracting.  
          Default is end of all P-cube/TOVS files found.
       GRAT_COLOR: set this keyword to a non-zero color index to display the
          graticule overlay (Default is no overlay)
       LABELS: string array of dates of the files found and extracted
          from, used for label in lower left corner of each displayed frame.
       MAP_COLOR: set this keyword to a non-zero color index to display the
          map overlay (Default is no overlay)
       MAX_VALUE: the highest value to display.  Default is maximum
          non-fill_value
       MIN_VALUE: the lowest value to display.  Default is minimum
          non-fill_value
       SDS_INFO: a named variable returned with metadata for the sds_name,
          used to determine unit and sds_label to write on the 
          lower right corner of the display, and fill_value.
       START_DATE: if entered, the date to start extracting.  
          Default is beginning of all P-cube/TOVS files found.
       VERBOSE: set for verbose output summary

 EXAMPLE:
       ppp_animate, 'a_surface_albedo', START_DATE=1988001,
           END_DATE=1988020,DATA=data,SDS_INFO=info,LABELS=lab

       20 days of surface albedo, will be extracted and animated
       via xinteranimate

 NOTES:
       Warning:  this routine is extremely memory-intensive.  Calling
       it with a large number of dates may result in memory errors.

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


PPP_COMPARE

 NAME:
	ppp_compare

 PURPOSE:
	Displays a scatter plot of (scaled) data for two P-cube/TOVS SDS's 
       for a given date

 CATEGORY:
	HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       ppp_compare, x_sds_name, y_sds_name, date 

 INPUTS:
       x_sds_name: the string SDS name that will be 
          extracted and displayed on the X-axis;  the list of
          valid SDS names is returned as the name element of the 
          sds_description structure from ppp_toc
       y_sds_name: the string SDS name that will be 
          extracted and displayed on the Y-axis;  the list of
          valid SDS names is returned as the name element of the 
          sds_description structure from ppp_toc
       date: scalar integer (yyyydoy) or string ('yyyydoy') date to
          extract and display

 KEYWORDS:
       CURSOR: set this keyword for interactive cursor behavior 
          in the display window
       DIRECTORY: base directory with P-cube/TOVS files.  4-digit year
          subdirectories will be searched for P-cube/TOVS files.
          Default is ./
       MISSING: set to display "missing" (aka "fill" values)
          Default is only to display values where both are non-missing.
       NEW_WINDOW: set this keyword to open a new window for display
       VERBOSE: set for verbose output summary
       _EXTRA=extra_keywords: This routine is essentially a wrapper
          to IDL's plot routine, so any extra keywords entered will
          be passed to the plot command

 RESULT:
       A scatter plot of the results

 EXAMPLE:
       ppp_compare, 't_temperature-700','t_temperature-850', 1988020,
          title='TOVS temperature 700 vs 850 mb',/cursor

       A scatter plot of values where both SDS's are non-missing values
       will be displayed in the current window.  The mouse will be
       activated to return data values as it is dragged across the
       display plot

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


PPP_EXTRACT

 NAME:
	ppp_extract

 PURPOSE:
	Extracts an array of SDS data of a given type and list of dates.

 CATEGORY:
	HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       result = ppp_extract, data, sds_name 

 INPUTS:
       sds_name: the string SDS name that is returned as the name 
          element of the sds_description structure from ppp_toc

 OUTPUTS:
       data: the data array for this sds_name extracted from each
          file corresponding to dates

 KEYWORDS:
       DATES: integer or string array of dates [yyyydoy,yyyydoy,...]
          Default is dates of all P-cube/TOVS files found.
       DIRECTORY: base directory with P-cube/TOVS files.  4-digit year
          subdirectories will be searched for P-cube/TOVS files.
          Default is ./
       END_DATE: if entered, the date to stop extracting.  
          Default is end of all P-cube/TOVS files found.
       LABELS: string array of dates of the files found and extracted
          from
       RAW: set this keyword to retrieve raw stored data
          Default is to return scaled data
       SDS_INFO: a named structure with information about this SDS
          includes unit, SDS label, fill value, etc.
       START_DATE: if entered, the date to start extracting.  
          Default is beginning of all P-cube/TOVS files found.
       VERBOSE: set for verbose output summary

 RESULT:
       This function returns 1 on success, or 0 in the event of an error   

 EXAMPLE:
       result = ppp_extract( data,'a_surface_albedo',
                       dates=[1988001,1988002],labels=labels)

       The returned data array will contain 3-D surface albedo 
          (cols x rows x 2 days).
       The returned labels array will be a string array with
          the date of each layer found

 NOTES:
       Dates with no corresponding P-cube/TOVS files are reported and ignored.

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


PPP_PLATFORM

 NAME:
       ppp_platform

 PURPOSE:
       Allows user to select either P-cube or TOVS data.

 CATEGORY:
       HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       ppp_platform

 INPUT:

 RETURN VALUE:
       1 - use P-cube data
       2 - use TOVS Northern Hemisphere Path-P Daily data
       3 - use TOVS Northern Hemisphere Path-P Monthly data 
       4 - use TOVS Southern Hemisphere Path-P Daily data

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


PPP_PLOT

 NAME:
	ppp_plot

 PURPOSE:
	Displays a plot of data at a given pixel,
       for a given SDS and a set of dates

 CATEGORY:
	HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       ppp_plot, sds_name, column, row 

 INPUTS:
       sds_name: the string SDS name that will be extracted and 
          sliced for display (valid SDS names are returned as 
          the name element of the sds_description structure from ppp_toc)
       column,row: the data coordinates (0..66) to slice and display

 KEYWORDS:
       CURSOR: set this keyword for interactive cursor behavior 
          in the display window
       DATES: integer or string array of dates [yyyydoy,yyyydoy,...]
          Default is dates of all P-cube/TOVS files found.
       DIRECTORY: base directory with P-cube/TOVS files.  4-digit year
          subdirectories will be searched for P-cube/TOVS files.
          Default is ./
       END_DATE: if entered, the date to stop extracting.  
          Default is end of all P-cube/TOVS files found.
       LABELS: string array returned with dates of the files found 
          and extracted from, these will be used to determine 
          x-axis coordinates
       MISSING: set to include dates with "missing" (aka "fill" values),
          treated as NaN (not-a-number) on the plot.
          Default is only to display non-missing values
       NEW_WINDOW: set this keyword to open a new window for display
       RAW: set this keyword to retrieve raw stored data 
          Default is to get scaled data
       SLICE: name of a variable that will be returned with the
          data displayed on the y-axis
       START_DATE: if entered, the date to start extracting.  
          Default is beginning of all P-cube/TOVS files found.
       VERBOSE: set for verbose output summary
       XTICKS: the number of x-axis tick intervals to draw
          Default is 4 intervals (5 tick values will be labelled)
       _EXTRA=extra_keywords: This routine is essentially a wrapper
          to IDL's plot routine, o any extra keywords entered will
          be passed to the plot command

 RESULT:
       Plot of the slice at the input column,row

 EXAMPLE:
       ppp_plot, 't_temperature-700',10,20,dates=indgen(20)+1988020
          title='TOVS temperature 700 at pixel (10,20)',/cursor

       The slice of SDS data at column 10, row 20 from the 20 dates
       beginning January 20, 1988 will be extracted, and non-missing
       values will be plotted.  The mouse will be activated to return 
       data values as it is dragged across the display plot

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


PPP_PLOT_XPARAMS

 NAME:
	ppp_plot_xparams

 PURPOSE:
	Use an array of string dates ['yyyydoy'] to set up plot
       parameter xvalues, xtickvalues and number of ticks

 CATEGORY:
	P-cube/TOVS display

 CALLING SEQUENCE:
       ppp_plot_xparams, strdates, xvals, xtickv, xticks

 INPUTS:
       strdates: string array with year, day of year strings ['yyyydoy']
          for x-axis values
       xticks : the number of tick intervals to establish

 OUTPUTS:
       xvals: returned array with x values (julian dates) to plot
       xtickv : returned array with the tick values for xticks+1 labels

 EXAMPLE:
       dates = strcompress(string(indgen(10)+1988020),/rem)
       ppp_plot_xparams, dates, xvals, xtickv, xticks

       returned parameters can be used in a subsequent call to plot

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


PPP_READ

 NAME:
       PPP_READ

 PURPOSE:
       Reads a 2-D array of data from a file

 CATEGORY:
	HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       result = ppp_read( data, sds_name, filename )

 INPUTS:
       sds_name: name of the SDS
       filename: file to read

 OUTPUTS:
       data: a 2-D array of sds_name data read from filename

 KEYWORDS:
       RAW: set this keyword to return raw (unscaled) data 
          (default is to return scaled data)
       SDS_INFO: a named structure returned with information about this SDS
          includes unit, SDS label, fill value, etc.
       VERBOSE: set for verbose output
       
 RESULT:
       1 on success, 0 otherwise

 EXAMPLE:
       filename = '/usr4/data/pcube/1988/ppp_n100_1988352_daily.v0.5.hdf'
       result = ppp_read(data,'a_surface_albedo', filename,SDS=info)

       The returned data array will contain scaled surface albedo data
          from the Pcube file for day 352 of 1988
       The returned info structure will contain SDS-specific
          information for these data (name, label, units, fill_value,
          etc)

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


PPP_RESTORE

 NAME:
	ppp_restore

 PURPOSE:
	Restores an array of extracted SDS data and accompanying metadata

 CATEGORY:
	P-cube/TOVS data tools

 CALLING SEQUENCE:
       ppp_restore, data, labels, sds_info, filename

 INPUTS:
       filename: the filename to create and write to

 OUTPUTS:
       data: a 2- or 3-D data array
       labels: string array of labels for each layer of data;
          the number of labels will match the size of data's
          3rd dimension (or be 1 if data is a single layer)
       sds_info: a named structure with information about this
          data, includes name, units, SDS label, fill value, etc.
 KEYWORDS:
       VERBOSE: set for verbose output summary

 EXAMPLE:
       status = ppp_extract (data,'a_surface_albedo',start_date=1988001,
                end_date=1988031,labels=labels,sds_info=info)
       if 1 eq status then ppp_save, data, labels, info,
                'surf_albedo.dat',/verbose
       (in a later session:)
       ppp_restore, data, labels, info, 'surf_albedo.dat',/verbose

       The returned data, labels, and info variables will contain
       saved values from the earlier session

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


PPP_SAVE

 NAME:
	ppp_save

 PURPOSE:
	Saves an array of extracted SDS data and accompanying metadata

 CATEGORY:
	P-cube/TOVS data tools

 CALLING SEQUENCE:
       ppp_save, data, labels, sds_info, filename

 INPUTS:
       data: the 2- or 3-D data array extracted via ppp_extract
       labels: string array of labels for each layer of data;
          the number of labels must match the size of data's
          3rd dimension (or be 1 if data is a single layer)
       sds_info: a named structure with information about this SDS
          returned from sds_extract, includes unit, SDS label, 
          fill value, etc.
       filename: the filename to create and write to

 KEYWORDS:
       VERBOSE: set for verbose output summary

 EXAMPLE:
       status = ppp_extract (data,'a_surface_albedo',start_date=1988001,
                end_date=1988031,labels=labels,sds_info=info)
       if 1 eq status then ppp_save, data, labels, info,
                'surf_albedo.dat',/verbose

       The extracted data array and metadata will be saved to the
          file 'surf_albedo.dat', and can be restored via ppp_restore

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


PPP_SHOW

 NAME:
	ppp_show

 PURPOSE:
	Reads and displays a grid of P-cube/TOVS SDS data for a given date

 CATEGORY:
	HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       ppp_show, sds_name 

 INPUTS:
       sds_name: the string SDS name that is returned as the name 
          element of the sds_description structure from ppp_toc

 OUTPUTS:

 KEYWORDS:
       CURSOR: set this keyword for interactive cursor behavior 
          in the display window
       DATA: a named variable returned with the requested data layer
       DATE: integer or string date of daily file to read 
          (yyyydoy or 'yyyydoy').  This keyword is ignored for
          ancillary sds_name's.  Default is 1988001.
       DIRECTORY: base directory with P-cube/TOVS files.  4-digit year
          subdirectories will be searched for P-cube/TOVS files.
          Default is ./
       GRAT_COLOR: set this keyword to a non-zero color index to display the
          graticule overlay (Default is no overlay)
       IMAGE: an 8-bit image of the displayed window
       LABEL: string to write to the lower left corner of the display
          Default is the date as mm-dd-yyyy
       LEGEND_TITLE: string to write as a legend title
          Default is the units from the file's sds_info
       MAP_COLOR: set this keyword to a non-zero color index to display the
          map overlay (Default is no overlay)
       MIN_VALUE,MAX_VALUE: the min/max data values to display
          (values in this range will be scaled linearly)
          Default is min/max of non-fill_value data.
       MULTIPLY: multiplication factor for resampled output.  Default is 10.
       NEW_WINDOW: set this keyword to open a new window for display
          if NEW_WINDOW = -1 then do not display data'
       SDS_INFO: a named variable returne with metadata for the sds_name,
          will be used to determine unit and sds_label to write on the 
          lower right corner of the display, and fill_value.
       SDS_LABEL: string to write to the lower right corner of the display
          Default is the sds label from the file's sds_info
       VERBOSE: set for verbose output summary

 RESULT:
       A window will be presented with the data scaled appropriately
          for the type of data.

 EXAMPLE:
       sds_name='a_surface_albedo'
       ppp_show, sds_name, DATE=1988020, DATA=data, IMAGE=image, $
                 sds_info=sds_info, map=196, grat=196,/cursor

       data will contain a 67x67 fltarr with AVHRR surface albedo values.
       sds_info will contain sds metadata for AVHRR surface albedo.

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


PPP_STATS

 NAME:
	ppp_stats

 PURPOSE:
	Prints summary statistics (min, max, fill_value, % missing, non-missing
       avg and standard deviation) for SDS data for a list of dates.

 CATEGORY:
	HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       ppp_stats, sds_name 

 INPUTS:
       sds_name: the string SDS name that is returned as the name 
          element of the sds_description structure from ppp_toc

 KEYWORDS:
       DATES: integer or string array of dates [yyyydoy,yyyydoy,...]
              Default is dates of all P-cube/TOVS files found.
              This parameter is ignored for ancillary data SDSs.
       DIRECTORY: base directory with P-cube/TOVS files.  4-digit year
          subdirectories will be searched for P-cube/TOVS files.
          Default is ./
       END_DATE: if entered, the date to stop extracting.  
              Default is end of all P-cube/TOVS files found.
              This parameter is ignored for ancillary data SDSs.
       GLOBAL_STATS: an anonymous structure with global values
              of displayed statistics for all dates found 
       LUN: file unit to write output to.  Default is -1 (stdout)
       START_DATE: if entered, the date to start extracting.  
              Default is beginning of all P-cube/TOVS files found.
              This parameter is ignored for ancillary data SDSs.

 EXAMPLE:
       ppp_stats, 'a_surface_albedo',dates=[1988001,1988002]

       Summary statistics for Jan. 1 and 2, 1988 AVHRR surface albedo
       will be printed.

 NOTES:
       Dates with no corresponding P-cube/TOVS files are reported and ignored.

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


PPP_TOC

 NAME:
	ppp_toc

 PURPOSE:
	Prints a table of contents of data from P-cube or TOVS HDF files.
       "P-cube" was coined to refer to combined data from the three Polar
       Pathfinder data sets (Polar AVHRR, TOVS Path-P, and SSM/I).  It is
       also a pun on the data structure, which is essentially a hypercube of 
       gridded data with dimensions cols x rows x parameters x time.

 CATEGORY:
	HDF Interface to P-cube/TOVS data files

 CALLING SEQUENCE:
       ppp_toc, sds_descriptions, dates

 OUTPUTS:
       sds_descriptions: variable that is returned with an array
         of SDS_INFO structures, one for each SDS in these P-cube/TOVS files.
       dates: variable that is returned with a string array of the 
         dates of the available data, as 4-digit year and day of year
         (yyyydoy)

 GLOBAL VARIABLES:
       platform_index: 1 - use P-cube data
                       2 - use TOVS Northern Hemisphere Path-P Daily data
                       3 - use TOVS Northern Hemisphere Path-P Monthly data 
                       4 - use TOVS Southern Hemisphere Path-P Daily data

 KEYWORDS:
       DIRECTORY: base directory with P-cube/TOVS files.  4-digit year
          subdirectories will be searched for P-cube/TOVS files.
          Default is ./
       VERBOSE: set for verbose output summary

 EXAMPLE:
       ppp_toc, SDS_DESC, sds_descriptions, DATES=dates, DIR='/CDROM/PCUBE/DATA/'

       The sds_descriptions and dates for files in '/CDROM/PCUBE/DATA/'
       year subdirectories will be returned.  A summary will be displayed.

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


SSMI_CONVERT

 NAME:
	ssmi_convert

 PURPOSE:
	Use a spherical earth model to convert geographic coordinates to
	azimuthal equal-area or equal-area cylindrical grid coordinates
	(for SSM/I EASE-Grids, 25 km, 12.5 km)

 CATEGORY:
	Grid coordinate conversion

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

 INPUTS:
       grid: projection name '[NSM][lh]'
             (where l="low" res (25km), h="high" res (12.5km)
       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)

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

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

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


SSMI_INVERSE

 NAME:
	ssmi_inverse

 PURPOSE:
	Use a spherical earth model to convert azimuthal equal-area 
       equal-area cylindrical grid coordinates to geographic coordinates
	(for SSM/I EASE-Grids, 25 km, 12.5 km)

 CATEGORY:
	Grid coordinate conversion

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

 INPUTS:
       grid: projection name '[NSM][lh]'
             (where l="low" res (25km), h="high" res (12.5km)
	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 = ssmi_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.)


IDL TOVS Path-P tools directory

TOVS Path-P data users will need to look in the directory where the IDL tools were installed from the NSIDC TOVS Path-P FTP site. If the tools are not already installed, see the Getting Started section of this tutorial for installation instructions.