User's Guide

TAB2STAT

Convert a labeled table to a LAS statistics file.

Function:

Allows the user to convert a labeled table (LT) file to a LAS statistics file. If the statistics file already exists, it is updated; otherwise, a new statistics file is created. If the statistics level (image, class, or site) already exists but does not contain the specified data, the data is inserted for that level; otherwise, a new node is created at that level (old data is never overwritten).
There are two types of statistics that can be converted: polygon and the mean and covariance matrix.
The data is compatible between the two file formats; however, the LT attribute names and the LAS statistics class and site names are not.

Parameters:

INLT
Input labeled table. The LT files are not cataloged; therefore, the value of INLT is the host file name. Directory paths may be specified using the host computer file naming conventions.
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. Subfile names are generated by appending an ascending numeric value to the master LT file name.

OUTSTAT
Output statistics file. If the statistics file already exists, new data is inserted to the correct level. If the incoming level is already in the statistics file and has data, then the level is appended with an "_x" where x is an ascending numeric value starting with 1. A new statistics file is created if there is no file.

FTYPE
File type. Specifies the type of LT that is being converted to a statistics file. The user must know what type of LT is being used.
   = COVAR:    Covariance matrix information
   = POLY:     Polygon information
STATSTYP(--)
Statistics type. Specifies the statistics type(s) to copy data into. STATSTYP is a three-value parameter allowing the user to specify any combination of types. The default is to process all types of the statistics file. Valid values are:
  = IMAGE:   Copy data into the image level
  = CLASS:   Copy data into the class level
  = SITE:    Copy data into the site level
CLASSATR("CLASS")
Class attribute. Specifies which LT attribute name is to be used for the LAS statistics class.

SITEATR("SITE")
Site attribute. Specifies which LT attribute name is to be used for the LAS statistics site.

LEVELATR("LEVEL")
Level attribute. Specifies which LT attribute name is to be used for the LAS statistics level is REQUIRED only when FTYPE = COVAR.

POLYNATR("REGNUM")
Polygon number attribute. The LT attribute name of the field that contains the unique number of each polygon; it is REQUIRED only when FTYPE = POLY.

COORSATR("Y","X")
Coordinate attribute. The attribute name of the field that defines the coordinates of each of the points that create the polygon. The first value is in Y direction and the second value is in the X direction; it is REQUIRED only when FTYPE = POLY.

CLASSNAM(--)
Class name. A list of LT attribute values (CLASSATR) that defines class names for the output statistics file. Records from the LT file are copied only if the value of CLASSATR matches the list defined by CLASSNAM. The default implies all classes are selected.

SITENAM(--)
Site name. A list of LT attribute values (SITEATR) that defines site names for the output statistics file. Records from the LT file are copied only if the value of SITEATR matches the list defined by SITENAM. The default implies all sites are selected.
The following table shows valid levels for specific types of data:
    Statistics Data Type        Valid Types 
    ____________________        ____________

    POLYGON                     SITE
    COVARIANCE_MATRIX           IMAGE, CLASS, SITE

Examples:

LAS> tab2stat inlt=[home.images]phoenix outstat=phoenix ftype=covar statstyp=-- classatr=class siteatr=site levelatr=level polynatr=regnum coorsatr=(y,x) classnam=landuse sitenam=water
All records in LT PHOENIX.LT under the HOME directory and in the subdirectory IMAGES which have a CLASSNAM of LANDUSE and a SITENAM of WATER are copied to the LAS statistics file PHOENIX.STAT.
LAS> tab2stat inlt=phoenix outstat=phoenix ftype=poly statstyp=(class,site) classatr=landuse siteatr=water levelatr=level polynatr=regnum coorsatr=(y,x) classnam=(industrial,agr) sitenam=(river,lake)
Selected records in LT PHOENIX.LT are copied to the LAS statistics file PHOENIX.STAT. LT label name LANDUSE is used for the statistics class, and LT label name WATER is used for the STAT site. Only those records that have the specified LT label values are copied; i.e., the value for LANDUSE is required to be INDUSTRIAL or AGR, and the value for WATER is required to be RIVER or LAKE. Also, the statistics level is required to be at the class or site level (records for the image level are not copied).

Description/Algorithm:

The input LT is opened and the definition records are read. The output LAS statistics file is opened. If the statistics file already exists, the new data is appended to the end of the file. Old data is never written over. If there is no statistics file, then a new statistics file is created.

Records are read from the LT. If the statistics level, class name, and site name match, the data is written to the statistics file. If the statistics level already exists but does not contain the specified data, the data is inserted at that level; otherwise, a new node is created at that level (old data is never overwritten).

After all records of the LT have been read and copied to the LAS statistics file, the files are closed and a standard completion message is written to the user's terminal.

The LT file type POLY needs the following attribute parameters:

  Parameter    Data  
  Name         Type     Description
  _________    ____     ___________
  CLASSATR     C*(*)    Class attribute name
  SITEATR      C*(*)    Site attribute name
  POLYNATR     I*4      Unique number of each polygon
  COORSATR 1   I*4/R*4  Row number of point (Y)
  COORSATR 2   I*4/R*4  Column number of point (X)

The LT file type COVAR needs to contain the following attribute parameters:

  Parameter    Data
  Name         Type     Description
  _________    ____     ___________
  CLASSATR     C*(*)    Class attribute name
  SITEATR      C*(*)    Site attribute name
  LEVELATR     C*(*)    Level attribute name

The LT file type COVAR needs to contain the following attribute names:

  Attribute    Data  
  Name         Type     Description
  _________    ____     ___________
  INDEX        I*4      Unique index number
  NBANDS       I*4      Number of bands in image
  NPOINTS      I*4      Number of points in area
  MEAN         R*8      Mean vector
  COVAR        R*8      Covariance matrix

The data is compatible between the two file formats; however the LT attribute names and the LAS statistics class and site names are not. The differences are listed in the following table.


      LABELED TABLE		  STATISTICS FILE
________________________________________________________________
                          |
Allows any number of      | Allows a class and site to define   
attribute names to define | the data.  Input parameter CLASSATR 
the data.                 | specifies which attribute name is to 
                          | be used for the class.  Input pa-
                          | rameter SITEATR specifies which at-
                          | tribute name is to be used for the 
			  | site. 
                          |
Attribute name may contain| A class may have more than one site. 
duplicate values.         | Sites cannot have duplicate names;  
			  | so if the site already exists, the 
			  | site name is appended with "_x",  
			  | where x is an ascending numeric 
			  | value starting with 1.  
                          |                         
Attribute name and value  | The class and site names cannot have  
may be embedded with      | blanks embedded; so all blanks are   
blanks.                   | replaced by "_" by TAB2STAT.   
                          |
Data type of attribute    | Data type of class and site names    
names may be character,   | are required to be character.  The   
integer, or real.         | character representation of other    
                          | data types, i.e., BYTE, I*2, I*4,  
                          | R*4, R*8, delimited by quotes, is     
                          | used.
                          |
Attribute name and value  |   CREATING NEW STATS FILE 
may be null.              |
			  | Class and site names cannot be null. 
                          | If the class is null, it is assigned 
                          | a value of "CLASS_x" where x is an 
                          | ascending numeric value starting 
                          | with 1.  If the site is null, it is 
			  | assigned a value of SITE.
			  |
Attribute name and value  |   ADDING TO STATS FILE 
may be null.		  |
			  | If the stat file has a class and 
			  | name of CLASS_1, SITE and an incom-
                          | ing class and site name is null-- 
                          | the name assigned is CLASS_1,SITE_1.

Nonfatal Error Messages:

None.

Fatal Error Messages:

[tab2stat-attribute] LT attribute name for <XXXXX> not found
Error encountered when the parameter <XXXXX> is not found in the LT. Check LT for correct value. In the case of LEVELATR and COORSATR 1, the wrong FTYPE may have been entered instead of an incorrect ATR value.
[tab2stat-bigpoly] Too many points in polygon
Error encountered when trying to process a polygon that has too many points. Check the constant MAX_POINTS for the maximum number.
[tab2stat-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 or contact system manager.
[tab2stat-esite] Error looking for open site in stats file
An error occurred looking for an open site to enter information. Check for available sites in statistics file.
[tab2stat-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.
[tab2stat-level] Polygon data is required to be at the site level
An error in processing polygon information. When processing polygon information, SITE must be one of the entries in the STATSTYP. Also, polygon information must be at the site level.
[tab2stat-newclass] Error creating new CLASSNAM node in statistics file
Error encountered trying to create a new CLASSNAM node in the statistics file. Probable cause is an invalid class name.
[tab2stat-newsite] Error creating new SITENAM node in statistics file
Error encountered trying to create a new SITE node in the statistics file. Probable cause is an invalid site name.
[tab2stat-write] Error writing to the statistics file
Error writing data to the LAS statistics file.
[tab2stat-dtype] Invalid data type for COORSATR
The data type of COORSTAR is not one of the allowed types. Refer to the Description/Algorithm for a list of the allowable data types.

User Notes:

TAB2STAT is a part of the file interface system. Other programs related to TAB2STAT 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

In addition to the previously listed programs, some TAE procedures have been written to transfer data from a source file to a destination file. These include the following programs.

      Program   Description
      _______   ___________

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

For more information about the labeled table interface system, run the LT program.