SCATMECH > Classes and Functions > Utility > Table

class Table

The class Table handles the storage and interpolation of a table of values or a functional dependence. The table may be assigned a single value, a functional form, or a table of numbers retrieved from a file. Three file formats are available for storing the data in a file. These formats, along with the functional form, are described below. Note that files are read into an internal cache. A call to ClearTableCache() must be made to clear that cache, if the file is known to change during program execution.

Whether the Table contains a single value, a functional form, or a table of numbers, it is treated as if it were a table of values, with the first column being the independent variable and subsequent columns being dependent variables. By default, the program will read the second column as the dependent variable.

Include file:

#include "scattabl.h"

Source code:

scattabl.cpp

Definition of public elements:

class Table 
{
     Table(const string& filename, int col=2);
     Table(const char* filename, int col=2);
     Table(double singlevalue=0.);
     Table(double *x,double *y,int n);
     Table(const std::vector<double>& x,const std::vector<double>& y);
     Table(const std::vector<pair<double,double> > v);

     double value(double l) const;

     int set(const std::string& filename, int ycol=2);

     enum InterpolationMode {
        LIN,
        LOG,
        SPLINE,
        LOGSPLINE
     };

     const std::string& get_name() const;
     friend std::ostream& operator<<(std::ostream& os,const Table& t);
     const VECTOR& get_table() const;

     enum InterpolationMode { LIN, LOG, SPLINE, LOGSPLINE };
     void set_interpolationx(InterpolationMode m);
     InterpolationMode get_interpolationx();
     void set_interpolationy(InterpolationMode m);
     InterpolationMode get_interpolationy();

     void set_parameter(const std::string& param,const std::string& value);
     std::string get_parameter(const std::string& param) const;

     static Table AskUser(const string& prompt,const string& deflt);
     static Table AskUser(const string& prompt,double deflt);
}

void ClearTableCache();

File Formats

When a Table is assigned a value, it may be assigned a single constant (double-precision) value, a functional form, or the name of a file. A single value can be assigned as in one of the following two statements:
  Table table1 = 1234.5678;
  Table table2 = "9876.5432";
The first of the above statements simply assigns the value 1234.5678 to table1. The second is a string assignment. If the string cannot be interpreted as a single number, then interpretation by one of the alternative expressions, given below, will be attempted.
A Table may also be assigned a simple functional form:
  Table table3 = "@x:1+x^2+x^3";
  Table table4 = "@y:(sin(y),cos(y))";
This simple functional form must start with an ampersand (@), be followed by a variable name (in the examples, x and y), a colon (:), and an expression. The second of the two examples returns two values. By default, only the first of the two values is used. However, if the Table is directed to use the third column, then the second value will be used. When a Table is used by a dielectric_function, two values will be needed.
The given function will be evaluated each time it is needed. That is, the values are not tabulated and there is is no interpolation.
If the string cannot be interpreted as a single value or a simple function, it will be interpreted to be the name of a file and the software will attempt to read that file. If the filename is followed by an exclamation point (!) and a number, say n, the n-th column will be used.
There are three file formats recognized by this class. The first is a simple whitespace-delimited table of values, the second generates a table from a function, and the third contains a simple functional form as described above with optional parameters. Each of these formats accepts comments, which is any text following a semicolon and continuing to the end of the line. When opening a file, the software first looks in the current directory of the application for the file. If the file does not exist, it uses the SCATMECH environment variable to find the file. The formats are described in more detail below.
Simple Table Format

The simple table format has two or more columns. Each row contains the same number of columns. The columns are separated by whitespace (space, tab, etc.). An example of a simple table is:
; These data are being used for an example...
  0   2    7   9
  0.1 2.2  6.8 9.9
  0.2 2.5  6.5 10.3 ; This is the third row
  0.3 2.8  6.1 10.9
  0.4 3.1  5.8 11.2
Notice the two comments. Each row must have the same number of columns. Text preceding the first row containing only numbers (aside from comments) is treated as a header. The file may have blank rows, which are ignored. Any row not having as many columns as the first row will be ignored.
Function Table Format

The function table format creates a table using a functional form. The function can have parameters, which are given default values that can be changed at a later time. The following example creates a generic Cauchy formula with three columns and three parameters:
PARAMETERS
   b 1.4580    ; The Cauchy B parameter
   c 0.00354   ; The Cauchy C parameter
   d 0         ; The Cauchy D parameter
END

; The wavelength is scanned from 0.2 um to 1.6 um in steps of 10 nm.
FOR lambda FROM 0.2 TO 1.6 BY 0.01

WORKING
   term1   b
   term2   c/lambda^2
   term3   d/lambda^4
   n       term1+term2+term3
   k       0
END

VALUES
   lambda  ; The first column
   n       ; The second column
   k       ; The third column
END
There are four blocks (PARAMETERS, FOR, WORKING, and VALUES) in the file.
In the PARAMETERS block, each of the parameters and their default values are listed. The block ends with the word END.
The second block iterates a variable (in the example: lambda) from a starting value, to an ending value, with an increment value. In this example, the variable is used as the first column in the table, but that does not have to be the case.
The third block (WORKING) contains pairs of variables and expressions. Each expression, which cannot contain spaces unless surrounded by double-quotation marks, is evaluated and assigned to the variable. The WORKING block must end with the word END.
The fourth block (VALUES) defines the values that make up the columns in the table. In this example, three values (lambda, n, and k) make up the table columns. The VALUES block must end with the word END.
Whitespace and linefeeds are ignored in the file, except insofar as they delimit words, and comments end at the next linefeed.
The parameters can be assigned different values later by using the set_parameter function. If the Table is a member of a Model class, then the parameters can be assigned through the Model's set_parameter function, as if the parameters were sub-parameters (e.g., via table.a, table.b, and table.c).
Simple Function Format

The simple function format does not create a lookup table. Instead, each time the function is needed, an expression is evaluated. An example for the simple function format, using the Cauchy formula above, is
PARAMETERS b 1.4580 ; The Cauchy B parameter c 0.00354 ; The Cauchy C parameter d 0 ; The Cauchy D parameter END @lambda:(b+c/lambda^2+d/lambda^4,0)

There are only two blocks (PARAMETERS and the function itself) in the file.
In the PARAMETERS block, each of the parameters and their default values are listed. The block ends with the word END.
The function itself uses the format described above. That is, the functional form must start with an ampersand (@), be followed by an independent variable name (in the example, lambda), a colon (:), and an expression. The expression can have multiple values, separated by commas and optionally in parentheses. The first value is treated as if it were the second column in a table, etc. The independent variable is treated as the first column in the table.
This example can be used as a dielectric_function, since the function returns two values, corresponding to columns 2 and 3 of a table (column 1 is lambda).
Whitespace and linefeeds are ignored in the file, except insofar as they delimit words, and comments end at the next linefeed.
The parameters can be assigned different values later by using the set_parameter function. If the Table is a member of a Model class, then the parameters can be assigned through the Model's set_parameter function, as if the parameters were sub-parameters (e.g., via table.a, table.b, and table.c.)
Notice that there is no WORKING section, so intermediate, temporary variables cannot be used.

Table(const std::string& filename, int col=2);
Table(const char* filename, int col=2);
Table(double singlevalue=0.);
Table(double *x,double *y,int n);
Table(const std::vector<double>& x,const std::vector<double>& y);
Table(const std::vector<pair<double,double> >& v);

Class constructors. In the first two constructors, the class will read columns 1 and col of the file given by filename. In the third constructor, the class will be initialized with a constant value singlevalue. In the fourth constructor, two arrays of length n, x and y will be used to fill the table. In the fifth and sixth constructors, vectors x and y or a vector of pairs v are used to fill the table. Note that the latter arrays must be of the same length.

Top of Page

double value(double lambda) const

Functions which evaluates the table at a specific value lambda.

Top of Page

int set(const string& filename, int ycol=2)

Function which will set the table contents based upon the string filename.. The function will read columns 1 and ycol.

Top of Page

enum InterpolationMode { LIN, LOG, SPLINE, LOGSPLINE }

By default, a table is interpolated linearly. Other choices are available to the user. The independent variable (x) may be interpolated linearly (LIN) or logarithmically (LOG). The dependent variable (y) may be interpolated linearly (LIN), logarithmically (LOG), as a cubic spline (SPLINE), or as a cubic spline on a logarithmic scale (LOGSPLINE).

Top of Page

void set_interpolationx(InterpolationMode m)
InterpolationMode get_interpolationx()
void set_interpolationy(InterpolationMode m)
InterpolationMode get_interpolationy()

Functions to set and get the interpolation mode for each of the axes of the Table. By default, a Table is interpolated linearly for both the xy axes. The independent variable (x) may be interpolated linearly (LIN) or logarithmically (LOG). The dependent variable (y) may be interpolated linearly (LIN), logarithmically (LOG), as a cubic spline (SPLINE), or as a cubic spline on a logarithmic scale (LOGSPLINE).

Top of Page

void set_parameter(const std::string& param,const std::string& value)
std::string get_parameter(const std::string& param) const

Functions to set and get parameters of the Table. The parameters may be interpolationx, interpolationy, or, if the Table is read in from a formula file, any of the parameters in the formula file.

Top of Page

static Table AskUser(const string& prompt,const string& deflt)
static Table AskUser(const string& prompt,double deflt)
Functions which prompt the user for either a value or a filename.
Example:
Table reflectance = Table::AskUser("Reflectance","reflectance.dat");
Top of Page

void ClearTableCache()

When table files are read, their information is read into a cache, increasing the speed at which subsequent calls are made or when reading multiple columns. This function clears that cache. Clearing the cache is useful, if it is known that the file needs to be read in again or memory needs to be freed.

Top of Page

For More Information

SCATMECH Technical Information and Questions
Sensor Science Division Home Page
Sensor Science Division Inquiries
Website Comments
Current SCATMECH version: 7.22 (April 2021)

class Table

Include file:

Source code:

See also:

Definition of public elements:

File Formats

Simple Table Format

Function Table Format

Simple Function Format

Table(const std::string& filename, int col=2);
Table(const char* filename, int col=2);
Table(double singlevalue=0.);
Table(double x,double y,int n);
Table(const std::vector<double>& x,const std::vector<double>& y);
Table(const std::vector<pair<double,double> >& v);

double value(double lambda) const

int set(const string& filename, int ycol=2)

enum InterpolationMode { LIN, LOG, SPLINE, LOGSPLINE }

void set_interpolationx(InterpolationMode m)
InterpolationMode get_interpolationx()
void set_interpolationy(InterpolationMode m)
InterpolationMode get_interpolationy()

void set_parameter(const std::string& param,const std::string& value)
std::string get_parameter(const std::string& param) const

static Table AskUser(const string& prompt,const string& deflt)
static Table AskUser(const string& prompt,double deflt)

Example:

void ClearTableCache()

For More Information

class Table

Include file:

Source code:

See also:

Definition of public elements:

File Formats

enum InterpolationMode { LIN, LOG, SPLINE, LOGSPLINE }

void set_interpolationx(InterpolationMode m) InterpolationMode get_interpolationx() void set_interpolationy(InterpolationMode m) InterpolationMode get_interpolationy()

Example:

For More Information

void set_interpolationx(InterpolationMode m)
InterpolationMode get_interpolationx()
void set_interpolationy(InterpolationMode m)
InterpolationMode get_interpolationy()