Close

Service Interruption

TOVS Path-P IDL Tools Tutorial

Introduction  |   Getting Started  |   Tutorial:  1  2  3  4  |   Example:  1  2  3  4  |   Extended Help

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

Routine Descriptions


 

COLORBAR

[Next Routine] [List of Routines] 
    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

[Previous Routine] [Next Routine] [List of Routines] 
 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

[Previous Routine] [Next Routine] [List of Routines] 
 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

[Previous Routine] [Next Routine] [List of Routines] 
 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

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

PPPU_ADD_SDS

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 

 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



 NOTES:

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

PPP_EXTRACT

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 

 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

 NOTES:

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

PPP_PLOT

[Previous Routine] [Next Routine] [List of Routines] 

 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



 NOTES:

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

PPP_PLOT_XPARAMS

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 

 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

[Previous Routine] [Next Routine] [List of Routines] 
 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

[Previous Routine] [Next Routine] [List of Routines] 
 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

[Previous Routine] [Next Routine] [List of Routines] 
 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.


 NOTES:

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

PPP_STATS

[Previous Routine] [Next Routine] [List of Routines] 
 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

[Previous Routine] [Next Routine] [List of Routines] 
 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

[Previous Routine] [Next Routine] [List of Routines] 
 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

[Previous Routine] [List of Routines] 
 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.

Contact Us | NSIDC Web Policy | Use & Copyright | Our Sponsors

The National Snow and Ice Data Center

Supporting Cryospheric Research Since 1976
449 UCB  University of Colorado  Boulder, CO 80309-0449

Cooperative Institute for Research in Environmental Sciences (CIRES)    University of Colorado Boulder