Source Documentation

Some general notes

Something on the terms used in comments

Class overview: Kernels

Class overview: Gui

Class overview: Command line version

Some notes on the variable types symbolic and continuous

Some notes on the command line version

Known bugs

Some general notes

Notation:

sz character string (char*)

f_ flag (bool)

Abbreviations:

`PoD`	Indicates a "Point of Danger" in the source code; mostly some field indexing. Seldom used. Be careful if you change something.
`ToDo`	Indicates something still to do.
`(hack!)`	Indicates a hack done. Should not be anywhere in the released code. However you will probably find some :-)

Global szModule at the top of a cpp file contains the file name. Used for exception handling.
No re-use of objects! Construct, load, prepare, use and destroy them!! For example the function Load() cannot be called twice in the lifetime of an object.
Counted objects have a private destructor. Use GetObject() to get an (additional) pointer to the instance. Call Release() once(!) for the pointer with which you have created the instance as well as for every pointer you got by a call to GetObject(). The instance deletes itself if it is not needed anymore.
Save() and Load() functions are a pair. If no re-loading is intended, there is just a function named Write().

Something on the terms used in comments

The algorithm is primarily intended for classification tasks. However it was originally invented to solve regression tasks. Thus the different (quantized) output values are named 'Intervals' and not 'Classes'.
The algorithm tries to merge data tuples with the same (quantized) output values to clusters. All tuples with the same (quantized) output value form a group. If the size of a group exceeds TParameter::N_G_Max, then approx. equally sized sub-groups are formed. All (sub-)groups for all possible (quantized) output values are enumerated and processed successively. The term 'output interval' now refers to this enumeration. Otherwise the term 'regular output interval' is used.
The terms 'cuboid', 'cluster' and 'rule' are used synonymously. However, the term 'cuboid' originally refered to the input space representation only.

Class overview: Kernels

Class	Module	Description
`TPnc TCuboid TIntervals TCuboids TCuboidsEx TCuboidsLists TAdjMat TAdjMatEx TAdjArr`	`pnc.h` `pnc.cpp`	Contains the class `TPnc` and all other necessary sub-classes for the PNC2 cluster algorithm.
`TParameter`	`para.h` `para.cpp`	`TParameter` is derived from `TParaSet` and serves as a struct with all parameters needed by the PNC2 cluster algorithm.
`TCluster` `TDFunc`	`cluster.h` `cluster.cpp`	`TCluster` encapsulates a model learned with the PNC2 cluster algorithm. It is used in combination with `TPrediction`. `TDFunc` encapsulates two function pointers that are used to improve performance of distance calculations in the input space.
`TPrediction`	`prediction.h` `prediction.cpp`	`TPrediction` predicts the unknown output value given the input based on the model learned with the PNC2 cluster algorithm. Note: The class `TCluster` encapsulates such a model.
`TLossFunction`	`lossfunc.h` `lossfunc.cpp`	Tracks some loss function results like mean absolute error (MAE) or relative number of misclassifications (MCE).
`TData`	`data.h` `data.cpp`	Class `TData` encapsulates data matrix with `nTup` rows and `nVar` columns. Note: The first column is regarded as output! Use `MoveToFirst()` to met this condition!
`TDataData`	`ddata.h` `ddata.cpp`	Encapsulates some necessary information from the learn data file like # variables, minima, maxima, feature, weights ...
`TParaSet`	`paraset.h` `paraset.cpp`	Base class for `TParameter`. Encapsulates only those parameters that are chosen within the parameter tuning.
`TProject`	`project.h` `project.cpp`	Encapsulates project settings. Abstract base class! GUI and batch interface each derive their own project classes.
`TExceptionAB` `TExceptionU`	`exception.h` `exception.cpp`	`TExceptionAB` encapsulates type 'A' and 'B' exceptions. These exceptions are intended for program development only and they should never been thrown in the released program. Note: Type 'B' exceptions are only generated in debug mode, i.e. if `DEBUG` is defined. `TExceptionU` encapsulates type 'U' exceptions. These exceptions are intended to be catched and shown to the user. They may occur in practise.
`TParaSetList`	`ParaSetList.h` `ParaSetList.cpp`	Type definition and utilities to store and use several parameter sets (`TParaSet`) in a single linked list (`TStdList`).
`TStdList`	`stdList.h`	Simple but time efficient single linked list template.
`TTask`	`task.h` `task.cpp`	A kind of struct with load and save functionality. Encapsulates a task, i.e. a set of parameter values for the PNC2 algorithm, that are used to generate a `TParaSetList` by building all possible combinations.
`-`	`defines.h`	Defines
`-`	`util.h` `util.cpp`	General utility functions to sort and randomize, to write values or times as formatted text, to quantize and de-quantize values and to write bits.
`-`	`fileutil.h` `fileutil.cpp`	Utility functions to read values or strings from a file stream. You can realize format-sensitive reading without the always read a whoole line concept.

Class overview: Gui

Class	Module	Description
`TProjectG`	`ProjectG.h` `ProjectG.cpp`	Encapsulates project settings. Derived from `TProject`.
`TTune`	`tune.h` `tune.cpp`	Tune parameters, i.e. learn and test model on several different data sets that are build randomly from a given `TData` object. Load and save functionality.
`ThrUseModel`	`ThrUseModel.h` `ThrUseModel.cpp`	Thread function: Use given model (`TCluster`) with given parameters (`TParameter`) to predict the unknown ouput values using only the inputs for a given `TData` object. Employs the class `TPrediction`.
`ThrTune`	`ThrTune.h` `ThrTune.cpp`	Tune parameters using `TTune`.
`ThrOpenProject`	`ThrOpenProject.h` `ThrOpenProject.cpp`	Thread function: Loads model, tuning results and data as specifed in given `TProjectG` object. Calls back to given c-style function when finished.
`ThrLoadData`	`ThrLoadData.h` `ThrLoadData.cpp`	Thread function: Calls `TData::Load()` in its execute function.
`ThrLearnModel`	`ThrLearnModel.h` `ThrLearnModel.cpp`	Thread function: Learns a model using `TPnc` and transforms the learned model afterwards to `TCluster` by calling `TPnc::ToTCluster()`.
`FVarTypes`	`FVarTypes.h` `FVarTypes.cpp`	Dialog to show and edit the variable types. Symbolic variables can be toggled between nominal and nominal (symbolic) type. Additional information like extrema, # symbols etc. is displayed for each variable.
`FOptions`	`FOptions.h` `FOptions.cpp`	Options dialog: Set those parameters of the PNC2 algorithm, that are not tuned within the parameter tuning.
`FOpenProject`	`FOpenProject.h` `FOpenProject.cpp`	Dialog that displays progress and other information when loading a model and data as specified in associated `TProjectG` object. Loading is done using the thread object `ThrOpenProject`.
`FMain`	`FMain.h` `FMain.cpp`	Main form of the GUI for the PNC2 cluster algorithm.
`FGuiOptions`	`FGuiOptions.h` `FGuiOptions.cpp`	Options dialog for Gui specific settings - directly saves to registry.
`FAbout`	`FAbout.h` `FAbout.cpp`	About-dialog with a few lines of text and an animated icon playing pinball with the dialogs frame.
`FEditSets`	`FEditSets.h` `FEditSets.cpp`	Form to edit the parameter sets for the parameter tuning.

Class overview: Command line version

Class	Module	Description
`TBatchInterface`	`bap.h` `bap.cpp`	Encapsulates batch interface for the PNC2 cluster algorithm.
`TParaSetResult TParaSetResults`	`SetResult.h` `SetResult.cpp`	`TParaSetResult` encapsulates loss function results and model characteristics for a model learned and tested several times on different data. `TParaSetResults` encapsulates several `TParaSetResult` objects, i.e. stores the results of several parameter sets used to learn and test a model on several different data sets.
`TProjectB`	`ProjectB.h` `ProjectB.cpp`	Encapsulates project settings. Derived from `TProject`.

Some notes on the variable types symbolic and continuous

The different symbols for nominal and ordinal variables are encoded as integer values. The maximum number of symbols for a variable to be considered as symbolic is:

max. # symbols defined in pnc.h as

Input 32 MAX_INP_SYMBOLS

Output 1024 MAX_OUT_SYMBOLS

The limit for inputs is a hard, implementation determined bound, as the bit masks for the covered symbols are stored in a 32 bit float!
The number of symbols is determined as range, i.e. as the maximum minus the minimum integer value. It's not the number of really occurring symbols!

Different usage of continuous and nominal variables

The distance metric is a weighted and normalized heterogeneous Minkowski Overlap Metric. The component wise distances are:

Continuous inputs	Weighted and normalized block wise distance from the cuboids' outer bounds
Symbolic inputs	Weighted and normalized (by overlap factor) Overlap Metric (0/1 metric)

Discretization (binning) for feature weight calculation and for the PNC2 output intervals, i.e. for the discretization of a continuous outputs:

Continuous	Equidistant or equal frequency binning for inputs and equidistant binning for output
Symbolic	None as variable is already symbolic

Generalization of cuboids:

Continuous	A kind of bounding box generalization
Symbolic	A symbol is covered by the generalized bit mask if it is covered by one or both bit masks of the two generalized cuboids

Some notes on the command line version

All paths in command line are relative to your current working directory.
Command line options
- /wp write protect output and log files
- /nh no halt on error
- /ns no sound
Error messages are written to file error.log.

Known bugs

Linefeed-carriage-return bug: ASCII data files from a UNIX system cannot be read because on UNIX lines are ended just by a linefeed whereas in windows lines end by a linefeed-carriage-return pair. Weird things happen and you get mysterios error messages. ;-(

	max. # symbols	defined in `pnc.h` as
Input	32	`MAX_INP_SYMBOLS`
Output	1024	`MAX_OUT_SYMBOLS`

`sz`	character string (char*)
`f_`	flag (bool)