User's Guide

STAT2TAB

Convert a LAS statistics file to a Labeled Table (LT)

Function:

Allows the user to convert a LAS statistics file to a labeled table (LT) file. There are two file types that can be converted: polygon and mean and covariance matrix.

Parameters:

Subcommand -POLY:
Converts polygon data from a LAS statistics file to a LT file. The output LT consists of two files: 

  1. Attribute file: Contains class and site names
  2. Data file:      Contains xy points of each polygon

INSTAT
Input statistics file. The name of the LAS statistics file to be converted into an LT. The statistics file may not contain class or site data.

OUTLT
Output labeled table. The LT may consist of one or multiple files. If there are multiple files, the first record of the master LT file contains a list of subfiles that are associated with it.

CLASSNAM(--)
Class name. A list of LAS statistics file class names that define attribute names for the output LT. Records from the statistics file are copied only if the class name in the statistics file matches a class name in the list defined by CLASSNAM. The default implies all classes are converted.

SITENAM(--)
Site name. A list of LAS statistics file site names that define attribute names for the output LT. Records from the statistics file are copied only if the site name in the statistics file matches a site name in the list defined by SITENAM. The default implies all sites are converted.

COMMENT(--)
Description of labeled table. File description of the LT. The default description for statistics data is: 


   File generated from file <XXXXXXXXX>
where <XXXXXXXXX> is the input statistics file name.
Subcommand -COVAR:
Converts mean and covariance matrix data from a LAS statistics file to a LT file. The output LT consists of one file. The output LT may contain the following: the statistics level, number of bands in the image, class name, site name, number of points, mean vector, and the covariance matrix.

INSTAT
Input statistics file. The name of the LAS statistics file to be converted into an LT. The statistics file may not contain class or site data.

OUTLT
Output labeled table. The LT may consist of one or multiple files. If there are multiple files, the first record of the master LT file contains a list of subfiles that are associated with it.

CLASSNAM(--)
Class name. A list of LAS statistics file class names that define attribute names for the output LT. Records from the statistics file are copied only if the class name in the statistics file matches a class name in the list defined by CLASSNAM. The default implies all classes are converted.

SITENAM(--)
Site name. A list of LAS statistics file site names that define attribute names for the output LT. Records from the statistics file are copied only if the site name in the statistics file matches a site name in the list defined by SITENAM. The default implies all sites are converted.

STATSTYP(--)
LAS statistics level. Specifies the statistics level(s) from which to copy data. STATSTYP is a three value-parameter allowing the user to specify any combination of levels. The default is to process all levels of the statistics file. 


  = IMAGE:  Process data at image level
  = CLASS:  Process data at class level
  = SITE:   Process data at site level

COMMENT(--)
Description of labeled table. File description of the LT. The default description for statistics data is: 


   File generated from file <XXXXXXXXX>
where <XXXXXXXXX> is the input statistics file name.

Examples:

  1. LAS> stat2tab-poly instat=[home.image]swusa outlt=phoenix classnam=-- sitenam=-- comment=--

    All polygons in statistics file SWUSA in the HOME directory and in the IMAGE subdirectory are copied to the LT named PHOENIX. The LT is defined by two files: PHOENIX and PHOENIX1. File PHOENIX consists of the attribute names and attribute values; file PHOENIX1 consists of the polygon data.

  2. LAS> stat2tab-poly instat=swusa outlt=phoenix classnam=(industrial,agr) sitenam=(river,lake) comment=--

    Selected polygons in statistics file SWUSA are copied to the LT named PHOENIX. The LT is defined by two files: PHOENIX and PHOENIX1. File PHOENIX consists of the attribute names and attribute values; file PHOENIX1 consists of the polygon data. All statistic nodes in SWUSA that have a class name of INDUSTRIAL or AGR and a site name of RIVER or LAKE are copied to the LT.

  3. LAS> stat2tab-covar instat=swusa outlt=phoenix classnam=(industrial,agr) sitenam=(river,lake) statstyp=-- comment=--

    Selected mean and covariance matrix data in statistics file SWUSA is copied to the LT named PHOENIX. The LT is defined by one file: PHOENIX. File PHOENIX consists of LAS statistic class and site names, mean vector, number of points, and the covariance matrix. Since parameter STATSTYP is set to null, all three levels of the statistics file are processed. If mean and covariance matrix exists at the image level, it is copied to the LT. If mean and covariance matrix exists at the class level and the class name is INDUSTRIAL or AGR, it is copied to the LT. If mean and covariance matrix exists at the site level, if class name is INDUSTRIAL or AGR, and if site name is RIVER or LAKE, it is copied to the LT.

  4. LAS> stat2tab-covar instat=swusa outlt=phoenix classnam=(industrial,agr) sitenam=(river,lake) statstyp=site comment=--

    Selected mean and covariance matrix data in statistics file SWUSA is copied to the LT named PHOENIX. The LT is defined by one file: PHOENIX. File PHOENIX consists of LAS statistic class and site names, mean vector, number of points, and the covariance matrix. Since parameter STATSTYP is set to SITE, only the site level of the statistics file is processed. If mean and covariance matrix exists at the site level, if class name is INDUSTRIAL or AGR, and if site name is RIVER or LAKE, it is copied to the LT.

Description/Algorithm:

The subcommand being executed determines the type of data to be processed (polygon points or covariance matrix). The input statistics file and output LT files are opened. The label vector which defines the LT format is written to the output LT file. The program parses the statistics file and determines if the data should be transferred to the LT.

If running the -POLY subcommand, data is to be transferred to the LT if the following conditions are met: 

  1. Current statistics node contains polygon data.
  2. Class name of the current statistics node matches a class
     name in parameter CLASSNAM.
  3. Site name of the current statistics node matches a site 
     name in parameter SITENAM.

If running the -COVAR subcommand, data is to be transferred to the LT if the following conditions are met: 

  1. Current statistics node contains covariance matrix.
  2. Current statistics level (image, class, or site) matches
     a level specified in parameter STATSTYP.
  3. The current level is class or site level, and the class 
     name of the current statistics node matches a class name 
     in parameter CLASSNAM.
  4. The current level is site level, and the site name of the 
     current statistics node matches a site name in parameter 
     SITENAM.
The corresponding LT file types are listed in the following table: 

  LAS Statistics
  File Type             LT File Types
  ______________        _____________

  Polygon               REGATT, REGXY
  Covariance Matrix     COVAR

The LT file type REGATT contains the following attribute names: 

  Attribute    Data  
  Name         Type     Description
  _________    ____     ___________

  REGNUM       I*4      Unique region number
  CLASS        C*(*)    Class name
  SITE         C*(*)    Site name

The LT file type REGXY contains the following attribute names: 

  Attribute    Data  
  Name         Type     Description
  _________    ____     ___________

  REGNUM       I*4      Unique region number
  X            I*4      Column number of point
  Y            I*4      Row number of point

The LT file type COVAR contains the following attribute names: 

  Attribute    Data  
  Name         Type     Description
  _________    ____     ___________

  INDEX        I*4      Unique index number
  LEVEL        C        Image, class, or site level
  NBANDS       I*4      Number of bands in image
  CLASS        C*(*)    Class name
  SITE         C*(*)    Site name
  NPOINTS      I*4      Number of points in area
  MEAN         R*8      Mean vector
  COVAR        R*8      Covariance matrix

Nonfatal Error Message:

  1. [stat2tab-write] Tried to write different matrix sizes into the LT

    This is a nonfatal error message informing the user that the matrix sizes vary. The matrix will be stored in the LT in the upper-left corner and filled with null values. The user will have to use caution when transferring data from the LT to another destination.

Fatal Error Messages:

  1. [stat2tab-dynamic] Error allocating dynamic memory

    Error encountered allocating buffers. Probable cause is that there is not enough memory on the system. The user should try to run the program again.

  2. [stat2tab-fatal] Fatal error encountered

    A fatal error was encountered during processing. Processing is terminated. The error message that is displayed immediately preceding this message is the specific error that was encountered.

  3. [stat2tab-fdata] Error reading <XXXXXXX> data

    Error reading polygon or covariance matrix data from the STAT file. Probable cause might be that the wrong subcommand was used, trying to convert polygon data with COVAR.

  4. [stat2tab-nameatr] Error reading STAT <XXXXX> name

    Error reading STAT class or site name from the STAT file. Probable cause is that the class or site name may be incorrect. Check STAT file for class or site names.

  5. [stat2tab-open] Error opening statistics file

    Error encountered opening the LAS statistics file. Probable cause may be an invalid file name, the statistics file does not exist, or the user does not have read access to the statistics file.

  6. [stat2tab-read] Error reading from the statistics file

    Error reading data from the LAS statistics file. Probable cause is a corrupt statistics file.

  7. [stat2tab-stnode] Error retrieving STAT node information

    Error encountered in determining the type of data stored in the current node of the statistics file. Probable cause is a corrupt statistics file.

  8. [stat2tab-tname] Error getting TAE name of statistics file

    Error encountered trying to retrieve the full TAE name of the LAS statistics file. Probable cause is that the specified statistics file does not exist.

User Note:

  1. STAT2TAB is a part of the file interface system. Other programs related to STAT2TAB are: 

          Program	Description
      _______   ___________

      GOF2TAB	Converts GOF file to a labeled table
      TAB2GOF	Converts labeled table to a GOF file
      STAT2TAB	Converts LAS statistics file to a labeled table
      TAB2STAT	Converts labeled table to a LAS statistics file

    In addition to the above programs, several TAE procedures have been written to transfer data from a source file to a destination file. 

          Program   Description
      _______   ___________

      GOF2STAT  Converts GOF file to LAS statistics file
      STAT2GOF  Converts LAS statistics file to GOF file