|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.debellor.core.Cell
public class Cell
Base class for all Data Processing Cells - elementary units which realize all kinds of data processing in Debellor. Basic properties of cells:
It is not obligatory for a cell to implement all of these functionalities. What exactly is implemented depends on the type of the cell. See next sections for more details.
Data in Debellor are represented and transfered
as a Cell.Stream
of Samples
,
accompanied by a Sample.SampleType
which defines the structure of samples
in a given stream.
Cell may be a data producer. In this case, to retrieve samples generated
by the cell you must open()
communication stream of the cell
and retrieve consecutive samples using method Cell.Stream.next()
of the returned
Cell.Stream
object or method next()
of the cell.
At the end, you must close the stream with Cell.Stream.close()
of the stream
or close()
of the cell.
Cell may be a data consumer. In this case, before the cell can be used,
it must be informed where to find input data, by calling setSource(Cell)
with the source cell as an argument.
In this way, the two cells become connected.
A number of interconnected cells form a graph called Data Processing Network (DPN).
DPN can be executed as a whole by calling method learn
or open
/next
/close
on the last cell.
Cell may be trainable:
before its use it must be trained how to process data.
Training of a cell consists typically of connecting it with a source of
training data (setSource(Cell)
),
setting parameter values (setParameters(Parameters)
or set(String, String)
or its variants for int/double/boolean value types)
and invoking its learning procedure, learn()
.
The learning procedure and the list of available parameters are specific
to the Cell's subclass actually used.
The term "learning procedure" as used in Debellor has very wide meaning. It includes not only generation of a decision system that could be used subsequently for data processing, but also any other data-driven operation that only accumulates some information (knowledge) internally in the cell and does not generate a stream of output samples. For example, learning procedure may implement:
erase()
.
After erasure the cell can be trained again.
Cell may be parameterized. In this case, you may call
setParameters(Parameters)
or set(String, String)
to pass parameter values before training or using the cell.
To find out what parameters are exposed by the cell, call getAvailableParams()
.
Usually, if you do not pass some required parameter, its default value
will be used - it depends, however, on implementation of the particular Cell subclass.
DPN can be executed concurrently in several threads.
To declare that some part of DPN should be executed in a separate thread,
before execution call newThread()
on the cell of DPN
which should lie on the boundary between threads.
Then, this cell and all its preceding (source) cells will run in a separate thread.
Call newThread()
on several cells to create more than 2 threads.
To implement new data processing algorithm, you have to
write a subclass of Cell
and override some or all of
protected methods named "on...
": onLearn()
, onOpen()
,
onNext()
, onClose()
, onErase()
.
They are called during calls to similarly named public methods (learn
, open
, ...).
If you do not need some method,
leave its default implementation, which will throw exception when called.
Do not call super
in overriders.
You can also override public method toString()
.
Other methods cannot be overridden.
If your cell represents a decision system (classifier, clusterer etc.),
the most important methods will be onLearn()
and onNext()
.
Training algorithm of the decision system will be implemented in onLearn()
,
while onNext()
will perform application of the trained system to the next input sample.
You will also have to override onOpen()
and onClose()
to open and close input stream before and after calls to onNext()
.
Optionally, you may also override onErase()
.
to erase trained decision model without deallocation of the whole cell.
In your implementation of on...()
methods,
input data can be accessed through the call to openInputStream()
,
which opens input stream
and returns it to the caller.
The caller may retrieve consecutive samples with Cell.Stream.next()
.
At the end, the caller must invoke Cell.Stream.close()
to close the stream.
It is possible to call openInputStream()
again after the stream has been closed.
If the cell is not trainable (e.g., it implements data reading from file),
you must inform the base class about this fact
through the call to Cell(boolean)
with argument false
in the cell's constructor.
In subclasses you can use:
protected
fields: parameters
, random
.
This is the "environment" provided by the base class for direct use in the subclass.
openInputStream()
-
call it to open the stream of input samples.
This is the only way to access input data. The subclass does not have
direct access to the source cell, only to the stream returned by openInputStream()
.
setAvailableParams(ParametersInfo)
-
call it in your constructor to provide information about available parameters.
This information will be returned to the user by getAvailableParams()
.
Providing this information is optional.
Nested Class Summary | |
---|---|
static class |
Cell.CellMethod
IDs of Cell's methods, used for error reporting. |
static class |
Cell.State
Constants for defining state of the cell. |
static class |
Cell.Stream
Represents a stream of samples flowing between two cells. |
Field Summary | |
---|---|
protected Parameters |
parameters
Values of parameters passed from the client, to be used in learn()
and/or during activity of the cell
(open() , Cell.Stream.next() , Cell.Stream.close() ). |
protected java.util.Random |
random
Random number generator that should be used by the subclass instead of the global one, so that the user can control (non)determinism of the cell's behavior. |
Constructor Summary | |
---|---|
protected |
Cell()
Statistics; currently switched off. |
protected |
Cell(boolean isTrainable)
|
Method Summary | |
---|---|
void |
close()
Closes the currently open output stream. |
void |
erase()
Erases the content of the cell created by learn() and brings the cell from
Cell.State.CLOSED to Cell.State.EMPTY state. |
ParametersInfo |
getAvailableParams()
Returns all available parameters with their default values and description of their meaning. |
Parameters |
getParameters()
Returns currently set parameters of the cell. |
void |
learn()
Invokes cell's learning procedure onLearn() . |
void |
newThread()
Sets that method Cell.Stream.next() of this cell will run in a separate thread. |
void |
newThread(boolean b)
Sets whether method Cell.Stream.next() of this cell will run in a separate thread. |
Sample |
next()
Returns next sample from the currently open output stream. |
protected void |
onClose()
Called by Cell.Stream.close() . |
protected void |
onErase()
Called by erase() . |
protected void |
onLearn()
Learning procedure of the cell. |
protected Sample |
onNext()
Called by Cell.Stream.next() . |
protected Sample.SampleType |
onOpen()
Called by open() . |
Cell.Stream |
open()
Opens the stream of samples generated by this cell. |
protected Cell.Stream |
openInputStream()
To be used by the subclass in order to open input stream from the source cell. |
void |
set(java.lang.String name,
boolean b)
Sets value of the parameter to string representation of boolean b . |
void |
set(java.lang.String name,
double x)
Sets value of the parameter to string representation of real number x . |
void |
set(java.lang.String name,
int k)
Sets value of the parameter to string representation of integer k . |
void |
set(java.lang.String name,
java.lang.String value)
Sets value of a single parameter of the cell. |
protected void |
setAvailableParams(ParametersInfo availParams)
To be used by the subclass in order to set information about parameters (names, default values, description) that will be returned to the user by method getAvailableParams() . |
void |
setParameters(Parameters parameters)
Sets parameters of this cell, to be used by the cell during learning or data processing. |
void |
setRandomSeed(long seed)
Sets seed of the random number generator used by this cell. |
void |
setSource(Cell source)
Connects this cell with another cell that will serve as a source of input data when this cell starts learning or operating. |
Cell.State |
state()
|
java.lang.String |
toString()
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
protected Parameters parameters
learn()
and/or during activity of the cell
(open()
, Cell.Stream.next()
, Cell.Stream.close()
).
Should be used directly in the subclass to read parameter values.
The subclass may freely modify this object.
Modifications will not be seen outside -
getParameters()
will return initial parameter values.
Moreover, when learn()
(for trainable cell) or open()
(for fixed cell) is called again, the initial values of parameters will be automatically restored.
protected java.util.Random random
Constructor Detail |
---|
protected Cell()
protected Cell(boolean isTrainable)
isTrainable
- True if the cell object being created is trainable,
which means that its initial state is Cell.State.EMPTY
and method learn()
can be called on this cell.
Otherwise, the cell is fixed:
it does not require learning and cannot be erased.learn()
Method Detail |
---|
public final Cell.State state()
public final ParametersInfo getAvailableParams()
System.out.print( cell.getAvailableParams() );
ParametersInfo
with information about available parameters.
null
if this information was not provided by the subclass
(in such case, consult documentation of the cell class).
Empty ParametersInfo
if there are no parameters that can be set by the user.public final void setParameters(Parameters parameters) throws CellAccessException
It is recommended as a general rule that if some required parameter has not been set before cell starts learning and/or processing data, subclass implementation will use its default value. However, clients should be aware that some subclasses may not follow strictly this rule.
Parameters can be set only if the cell is in Cell.State.EMPTY
(for trainable cells) or Cell.State.CLOSED
(for fixed cells).
CellAccessException
learn()
,
set(String, String)
public final void set(java.lang.String name, java.lang.String value) throws CellAccessException
CellAccessException
Parameters.set(String, String)
,
setParameters(Parameters)
,
learn()
public final void set(java.lang.String name, int k) throws CellAccessException
k
.
CellAccessException
public void set(java.lang.String name, double x) throws CellAccessException
x
.
Caution: x
is a real value and its conversion to String may
introduce rounding errors, so the value decoded later on may slightly
differ from the value passed to this method.
CellAccessException
public void set(java.lang.String name, boolean b) throws CellAccessException
b
.
CellAccessException
public final Parameters getParameters()
public final void setRandomSeed(long seed) throws CellAccessException
CellAccessException
public final void newThread(boolean b) throws CellAccessException
Cell.Stream.next()
of this cell will run in a separate thread.
CellAccessException
public final void newThread() throws CellAccessException
Cell.Stream.next()
of this cell will run in a separate thread.
CellAccessException
public final void setSource(Cell source) throws CellAccessException
null
to this method.
CellAccessException
public final void learn() throws CellException
onLearn()
.
Causes transition of the cell from Cell.State.EMPTY
to Cell.State.CLOSED
state.
Usually the learning procedure creates internal content of the cell,
for example: a decision model (classifier, clusterer etc.);
a set of buffered samples (in the case of a buffer cell);
results of an evaluation (e.g. TrainAndTest
) etc.
Only after training the cell can process data
in open()
, Cell.Stream.next()
and Cell.Stream.close()
methods.
Most cells require that the source of training data is provided
before learning is invoked.
This can be done by a call to setSource(Cell)
.
The cell may also expose a number of parameters that can be
set by the user in setParameters(Parameters)
or set(String, String)
to control behavior of learn()
.
Some cells may not implement learning, in which case
they are ready to process data just after construction.
Such cells are said to be fixed,
in contrast to the cells that require learning,
which are said to be trainable.
Initial state of a fixed cell after construction is Cell.State.CLOSED
.
Fixed cell cannot be erased and can never move to Cell.State.EMPTY
.
CellAccessException
- if the cell is not in Cell.State.EMPTY
state.
CellMethodNotImplementedException
- if method is not implemented in subclass.
CellInternalException
- if method fails for some other reason.
CellException
onLearn()
,
erase()
public final void erase() throws CellException
learn()
and brings the cell from
Cell.State.CLOSED
to Cell.State.EMPTY
state.
This is a reversion of learn()
.
After erase()
the cell can be trained again.
Note that only the content is erased, other fields of the cell,
like parameter values or source link, are not changed!
Implementation in subclasses should guarantee that the cell
after erasure behaves exactly in the same way as a newly allocated one,
with the same parameters.
CellException
learn()
public final Cell.Stream open() throws CellException
CellAccessException
- if the cell is not in Cell.State.CLOSED
.
CellMethodNotImplementedException
- if method is not implemented in subclass.
CellInternalException
- if method fails for some other reason.
CellException
public final Sample next() throws CellException
null
CellException
Cell.Stream.next()
public final void close() throws CellException
CellException
Cell.Stream.close()
protected final Cell.Stream openInputStream() throws CellException
CellException
protected final void setAvailableParams(ParametersInfo availParams)
getAvailableParams()
.
In the future, this information will be used also to validate parameters
supplied by the user (setParameters(Parameters)
, set(String, String)
)
and to automatically assign default values to parameters not assigned by the user.
protected void onLearn() throws java.lang.Exception
learn()
.
Must be overridden in all subclasses that implement trainable cells.
If your cell is not trainable, you must provide this information
to the Cell
base class by calling Cell(boolean)
instead of Cell()
in your constructor.
Overriders may safely assume that the cell is in Cell.State.EMPTY
state
when onLearn
is called - this is guaranteed by
implementation of learn()
.
java.lang.Exception
protected void onErase() throws java.lang.Exception
erase()
. Performs the actual erasure of cell content,
while erase
checks only against access violation and handles exceptions.
Must be overridden in subclasses if erasure is to be used.
Overriders may assume that the cell is in Cell.State.CLOSED
state.
java.lang.Exception
protected Sample.SampleType onOpen() throws java.lang.Exception
open()
. Performs the actual opening of
communication session,
while open
checks only against access violation and handles exceptions.
Must be overridden in subclasses if open
is to be used.
Overriders may assume that the cell is in Cell.State.CLOSED
state.
java.lang.Exception
protected Sample onNext() throws java.lang.Exception
Cell.Stream.next()
. Performs the actual generation of the next output sample,
while Stream.next()
checks only against access violation and handles exceptions.
Must be overridden in the subclass if next
is to be used, i.e.
if the subclass should generate some output data.
Overriders may assume that the cell is in Cell.State.OPEN
state.
java.lang.Exception
protected void onClose() throws java.lang.Exception
Cell.Stream.close()
. Performs the actual closing of
communication session,
while close
checks only against access violation and handles exceptions.
Must be overridden in subclasses if close
is to be used.
Usually the overrider will use onClose to release resources,
to let them be garbage-collected.
Overriders may assume that the cell is in Cell.State.OPEN
state.
java.lang.Exception
public java.lang.String toString()
toString
in class java.lang.Object
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |