tsCmdLineApp Class Reference
[Command line framework]

Framework class for command line application. More...

#include <tsAppMain.h>

Inherited by myDataReductionApp.

List of all members.

Public Types
enum	dfm_t { DFM, HDR }
Public Member Functions
virtual void	analyzeData (int argc, char *argv[])
virtual std::vector< measures >	process_file (dataFile &data, std::vector< lookupTable > &tables, std::string &fileName)=0
virtual double	getSampleTime (std::string fileName)=0
virtual int	getByteOrdering ()=0
virtual std::vector < TCLAP::SwitchArg >	additionalCmdLineSwitchArgs (void)
virtual void	parseAdditionalCmdLineSwitchArgs (std::vector< TCLAP::SwitchArg > &switches)
virtual std::vector< lookupTable >	getLookupTables (void)
virtual std::string	getLabelFileName (void)
virtual std::string	sharedDFM (void)
virtual dfm_t	getDFMType (void)

---

Detailed Description

Framework class for command line application.

tsCmdLineApp provides a set of methods needed to realize a command-line data reduction application. The class is meant to work as part of a simple application skeleton. The skeleton is provided in the file tsCmdLineMain.cpp:

/*
 An command line application framework for data reduction using 
 the timeSeries library
 
*/

#include "myDataReductionApp.h"

using namespace std;

#ifdef WIN32
int analysisMain (int argc, char *  argv[])
#else
int main (int argc, char *  argv[])
#endif
{   tsCmdLineApp* app = new myDataReductionApp();
    
    app->analyzeData(argc, argv);

    return 0;
}

tsCmdLineApp is an abstract class and cannot be used by itself. To create a new application you first create a new class derived from tsCmdLineApp -- in this case myDataReductionApp. This derived class must provide definitions for at least three of the member functions:

virtual std::vector<measures>  process_file(dataFile& data,  
                                            std::vector<lookupTable>& t, 
                                            std::string& s)=0;
virtual double getSampleTime(std::string)=0;
virtual int getByteOrdering()=0;

The functions getSampleTime and getByteOrdering specify necessary details of the dataset that are not included in the data definition file. The function process_file does all the work.

Features of a tsCmdLineApp based application

The framework provides a few key functions:

• Command-line parsing.
  • By default commands are of the form:

    USAGE: 
    
    tsCmdLineApp  [-n] [--] [-v] [-h] <filename> <filename> ...
    
    
    Where: 
    
    -n,  --new
        only process new files
    
    --,  --ignore_rest
        Ignores the rest of the labeled arguments following this flag.
    
    -v,  --version
        Displays version information and exits.
    
    -h,  --help
        Displays usage information and exits.
    
        <filename>
        (required)  (value required)  binary data file name
    
        <filename>  (accepted multiple times)
        (value required)  additional binary data file names
    

  • Additional command line switches can be specified
  • An essentially unlimited number of data files can be processed. Wildcards are expanded by the application under Windows. Windows shortcuts are also handled correctly.
• Measure file generation
  • Output files are generated in the same directory as the input files and are given a ".dat" extension. Each line of the output files contain tab-delimited measures corresponding to a single performance interval. One output file is generated for every data file listed on the command line.
• Title file generation
  • A title file is generated in the working directory of the tool. The title file has a default name of "labels.tit" but this can be changed by the application. The file contains a single line with tab-delimited labels for each measure that appears in the output files.
• Lookup tables
  • The framework has provision for an unlimited number of lookup tables to be parsed prior to the beginning of data processing. These lookup tables are passed to the process_file routine so that metadata can be extracted on a per-file basis.
• Exception handling
  • The framework provides for exception handling for all timeSeries library exceptions. Exceptions that affect only the processing of a single file cause that data file to be skipped but the application continues to process the remaining files on the command line. This ensures that errors caused by corrupt or anomalous data do not terminate an entire processing session.
• Compatible with both VIRTTEX .hdr files and the more general .dfm format

Typical Usage

Data files to be processed are expected to be stored in a single directory. If this is not the case, shortcuts or symbolic links can be used to collect the data file references into a single directory. The data files must have a file extension of .bin By default the framework expects that every .bin file will have a corresponding hdr or dfm file. However, if the file format is the same for every data file a singled shared hdr or dfm file can be used.

Assuming that all of the data files are contained in a directory called data , the following unix-style commands can process an entire dataset:

    tsCmdLineApp data/*.bin
    cat labels.tit data/*.dat > measures.txt

Running in a DOS shell the equivalent commands look like:

    tsCmdLineApp data\*.bin
    copy labels.tit+data\*.dat > measures.txt

The resulting measures.txt file is a labeled, tab-delimited text file that can be imported into Excel, Minitab, Systat or any other statitical analysis code. Adding new data to the dataset is trivial. Just copy the new files into the data directory and use the -n option to suppress processing of files that already have a corrsponding .dat file present:

    tsCmdLineApp -n data/*.bin
    cat labels.tit data/*.bin > measures.txt

---

Member Enumeration Documentation

enum tsCmdLineApp::dfm_t

Return type for the getDFMType method. Used to indicate the input file format

Enumerator:

DFM	designates the generic data format
HDR	designates the VIRTTEX post-process file header format

---

Member Function Documentation

virtual std::vector<TCLAP::SwitchArg> tsCmdLineApp::additionalCmdLineSwitchArgs

(

void

)

[inline, virtual]

specifies additional TCLAP switches

Returns:

returns a vector containing TCLAP::SwitchArg objects

The base class defines no additional switches. Override this method if you need to define added command line options.

Example:

 vector<SwitchArg> myDataReductionApp::additionalCmdLineSwitchArgs(void) {
     vector<SwitchArg> switches;
     SwitchArg printStates("s","states","print states",false);
     switches.push_back(printStates);
     return switches;
 }

Currently only TCLAP SwitchArg types are supported. These are simple on/off boolean switches without an argument.

void tsCmdLineApp::analyzeData	(	int	argc,
		char *	argv[]
	)			[virtual]

data analysis main

Parameters:

	argc	the number of command line arguments
	argv	an array of command line parameters

analyzeData processes the input data files using the following steps:

1. parses the command line arguments using the TCLAP command-parsing library ( http://tclap.sourceforge.net/ ).
2. makes a call to the getLookupTables method to retrieve a vector of lookup tables. By default this method returns a vector of zero length.
3. makes a call to the sharedDFM method to retrieve the path to a shared dfm or hddr file. If the name is non-null the file is parsed and used to interpret all data files processed. If sharedDFM returns a null string analyzeData will expect to find a .dfm or .hdr file for each .bin file processed.
4. For each data file on the command line:
   1. reads the data file into memory
   2. passes the file to process_data
   3. outputs the measures to the .dat file

Exceptions generated by the timeSeries classes are handled as appropriate. analyzeData itself throws no exceptions.

Normally this method should not be overidden by the derived class. However, it is declared virtual in case you think otherwise.

virtual int tsCmdLineApp::getByteOrdering

(

)

[pure virtual]

returns byte order

Returns:

must be either dataFile::BigEndian or dataFile::LittleEndian

Another pure virtual function that must be defined in the derived class. This member specifies the byte-ordering used by the computer that created the binary data files. dataFile::BigEndian is appropriate for Motorola style processors such as the PowerPC. dataFile::LittleEndian is appropriate for Intel-style processors.

virtual dfm_t tsCmdLineApp::getDFMType

(

void

)

[inline, virtual]

returns the data definition type

Returns:

either HDR or DFM

Determines the format of the data definition files. Currently this must be one of HDR for VIRTTEX .hdr file or DFM to specify the more general .dfm format.

The base class returns DFM so you must override this method to process VIRTTEX data.

virtual std::string tsCmdLineApp::getLabelFileName

(

void

)

[inline, virtual]

returns the label file name

Returns:

the name of the label file

The base class define the label file name as "labels.tit" Override this method to change the name.

virtual std::vector<lookupTable> tsCmdLineApp::getLookupTables

(

void

)

[inline, virtual]

reads lookup tables

Returns:

a vector of lookupTable objects

The base class defines no tables. Override this method to read lookup table data.

Example:

 vector<lookupTable> myDataReductionApp::getLookupTables(void) {
     string subjectTablePath="subject_data.txt";
     
     lookupTable subjectTable(subjectTablePath,"Subject");
     
     vector<lookupTable> tables;
     tables.push_back(subjectTable);
     
     return tables;
 }

virtual double tsCmdLineApp::getSampleTime

(

std::string

fileName

)

[pure virtual]

defines the sample time in seconds

Parameters:

fileName

the name of the data file including the .bin extension

Returns:

the sample time in seconds.

Another pure virtual function that must be defined in the derived class. getSampleTime can simply return a constant or it can use the supplied filename to parse a header file or a lookuptable to find the sample time.

virtual void tsCmdLineApp::parseAdditionalCmdLineSwitchArgs

(

std::vector< TCLAP::SwitchArg > &

switches

)

[inline, virtual]

parses additional TCLAP switches

Parameters:

switches

A vector of SwitchArg objects defined ty additionalCmdLineSwitchArgs

This method is called immediately after the command line is parsed. It returns SwitchArg objects that can be queried to determine their state. The method should take any action required to implement the switches.

The base class defines no additional switches. Override this method if you need to define added command line options.

Example:

 void myDataReductionApp::parseAdditionalCmdLineSwitchArgs(vector<SwitchArg>& switches) {
     SwitchArg printStates = switches[0];
     setPrintState(printStates.getValue());
 }

virtual std::vector<measures> tsCmdLineApp::process_file	(	dataFile &	data,
		std::vector< lookupTable > &	tables,
		std::string &	fileName
	)			[pure virtual]

reduces the data

Parameters:

	data	The data object representing the input file
	tables	A vector of lookup tables for metadata
	fileName	The input datafile name with .bin extension

process_file is the major data reduction method. It is a pure virtual method and must be provided by the derived class. The simplest form of the method computes measures for the entire run with no metadata:

 vector<measures>  myDataReductionApp::process_file(dataFile& data,  
                                                    vector<lookupTable>& tables, 
                                                    string& fileName) {
     vector<measures> myMeasures;
     measures meas;
     
     timeSeries<float> speed("VMPH",data);
     meas.entry("speed",speed.mean());
     meas.entry("max speed", speed[speed.max()]);
     
     myMeasures.push_back(meas);
     return myMeasures;
 }

Applications that require metadata tables can simply unpack them from the tables vector and use them as needed:

 lookupTable& subjectTable = tables[0];
 
 ostringstream subjectStr;
 subjectStr << subject;
 
 string gender = subjectTable.find<string>(subjectStr.str(),"Gender");
 string ageGroup = subjectTable.find<string>(subjectStr.str(),"Age");
 
 cout << "gender = " << gender << endl;
 cout << "age = " << ageGroup << endl;

When multiple performance intervals are present in the data, a measures object is computed for each one and the complete vector of measures is returned.

virtual std::string tsCmdLineApp::sharedDFM

(

void

)

[inline, virtual]

returns the shared data definition

Returns:

the name of a .dfm or .hdr file

If sharedDFM returns a non-null file name, that file is parsed as either a valid hdr or dfm file based on the extension. The resulting data definition is then used to interpret all remaining binary files.

The basse class returns sharedDFM=="" which results in the application looking for either a .hdr or .dfm file corresponding to each binary data file.

Override this class if all of your data files have the same format and you wish to avoid re-parsing the data definition for each file.