env.txt,v 0.4 1992/11/01 16:35:47 mume Exp
ENV Utilities Functions
-----------------------
The ENV net provides an interface to the environment (data files). It also
provides facilities for data normalisation, scaling and manipulation. The
ENV net is described in ENV.5. Here we describe routines for manipulating 
the data sets and vectors of an ENV net.

Associated with each ENV net is a list of data sets. A dataset is known by
a name and a filename. It contains vectors of data. In supervised
learning, the vectors are made of pairs of "input" and "expected output".

In an ENV section in an ".mmn" file (see ENV.5) the statement

data <name> <filename> <filetype>;

can be used to attach data sets to the ENV net. Several "data" statements
can be used. The ENV Network Services Function routine RCRead() will add
each data set to the ENV data list. Each data file is opened and read.
The data set is then pushed on a "stack" of datasets within the ENV data
structure making it the current set attached to the input of the ENV net.

A data set in an ENV net is recognised (internally) by pointers.
Associated with each dataset are two pointers: the dataset pointer and the
vector pointer. The dataset pointer is visible to the user, but the vector
pointer is not.

The functions described below permits the user to manipulate the datasets
and step through a particular one.

The stepping through a dataset is how vectors are fired at a network.

There is also another mean of attaching data files to an ENV net. This is
through the function AttachData also described below.


All of the routines  below make use of data types defined in ENV.h,
ENVP.h and net.h. In particular the argument "p" is used to refer to a
network pointer.


Attaching a Data File to an ENV Net
-----------------------------------
Another means of attaching a dataset to an ENV net other than the "data"
statement in an ENV net section of an ".mmn" file is the routine

obs_t *AttachData(p, fname, filetype, start, many, Name)
nn_t *p;
char *fname, *Name;
int  filetype, start, many;

This function will read the data from file "fname" of type "filetype"
(ASCTYPE is the only supported format, but a binary format called NI is
being added). The data is read starting from "start" and "many" data
vectors are read. If "many" is < 0 then all data is read. The data set is
then given the name "Name" and added to the dataset list of the ENV net
pointed to by "p". The pointer to the dataset is returned.



Stepping Through A Dataset
--------------------------
The function below is commonly used to select the next data vector in a
data set. The vector can then be propagated using the Relax Network
Services Function of the ENV net.

int StepEnv(p)

Point to net pattern. Return TRUE if next pattern exits, else return FALSE.



Resetting an ENV Net Dataset
----------------------------
  
ResetEnv(p)

Wraps vector pointer around to point to the first vector of the current dataset.


Dataset Stack Manipulation
--------------------------

PopCurrentPattern(p)		
nn_t *p;

Pops vector pointer from top of stack to become current pattern pointer.
If stack is empty the operation is not performed.


PushCurrentPattern(p)
nn_t *p;

Pushes pointer to current data pattern onto the stack. 


PushAndReset(p)
nn_t *p;

Pushes pointer to current data pattern onto the stack. 
Resets the current pattern pointer to point to first in current dataset.


PopDataAndCurrentPattern(p)
nn_t *p;

Pops the top data set from the stack to become current data set. It also
restores the vector pointer from the stack to become the current vector
pointer. 


PushDataAndCurrentPattern(p, dp)
nn_t *p;
obs_t *dp;

Makes the data set pointed to by dp the current data set. It pushes
the previous one on the stack. The previous vector pointer is also save on
the stack.


PushAndResetData(p, dp)
nn_t *p;
obs_t *dp;

Makes the data set pointed to by dp the current data set. It pushes
the previous one on a stack. It also resets the current pattern to the
first pattern in the dataset.


int EnvPatternCount(p)
nn_t *p;

Returns the number of vectors in the current dataset.


obs_t *EnvSetData(p, Name)
nn_t *p;
char *Name;

Return dataset pointer from a set name "Name". 
p is pointer to a net of ENV class. "Name" is the name of the set as
entered in the "data" statement of an ENV net or as provided to AttachData.
It returns NULL is the set was not found in the net's data set list.





