org.ptolemy.machineLearning.hmmAOM

Class ParameterEstimator

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.InstantiableNamedObj

ptolemy.kernel.Entity<T>

ptolemy.kernel.ComponentEntity<T>

ptolemy.actor.AtomicActor<TypedIOPort>

ptolemy.actor.TypedAtomicActor

ptolemy.actor.lib.aspect.AtomicCommunicationAspect

org.ptolemy.machineLearning.hmmAOM.ParameterEstimator

All Implemented Interfaces:

java.lang.Cloneable, Actor, CommunicationAspect, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Decorator, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

HMMGaussianEstimator

public abstract class ParameterEstimator
extends AtomicCommunicationAspect

This actor is a CommunicationAspect that, when its sendToken(Receiver, Receiver, Token) method is called, delays the delivery of the specified token to the specified receiver according to a service rule. Specifically, if the actor is not currently servicing a previous token, then it delivers the token with a delay given by the serviceTimeMultiplicationFactor parameter multiplied by the messageLength parameter specified in the port. If the actor is currently servicing a previous token, then it waits until it has finished servicing that token (and any other pending tokens), and then delays for an additional amount given by serviceTimeMultiplicationFactor * messageLength. In the default case of the messageLength = 1, the behavior is similar to the Server actor. Tokens are processed in FIFO order.

To use this communication aspect, drag an instance of this Bus into the model, and (optionally) assign it a name. Then, on any input port whose communication is to be mediated by this instance of Bus, open the configuration dialogue, select the tab with the name of the bus in the title and select the enable attribute. The message length is by default set to 1 but can be configured in this tab.

Several Bus communication aspects can be used in sequence. The order in which Tokens are sent through Buses depends on the order in which these are enabled via the DecoratorAttributes.

This actor is tested in continuous and DE.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Patricia Derler, Edward A. Lee

Pt.AcceptedRating:

Red (derler)

Pt.ProposedRating:

Yellow (derler)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ParameterEstimator.BusAttributes Bus Attributes.

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected double[][]	_A0 User-defined initial guess array for the state transition matrix.
protected int	_batchSize User-defined batch size.
protected double	_likelihood The likelihood value of the observations given the current estimates L(x1,....xT | \theta_p).
protected double	_likelihoodThreshold The likelihood threshold.
protected int	_nIterations User-defined number of iterations of the alpha-beta recursion.
protected int	_nStates Number of hidden states in the model.
protected double[]	_observations Observation array.
protected java.util.HashMap<java.lang.String,java.util.List<java.lang.Double>>	_observedTokens The observation tokens.
protected double[]	_priorIn The prior estimates used in the EM iterations
protected double[]	_priors Prior distribution on hidden states.
protected boolean	_randomize If true, then randomize the initial guess vectors.
protected double[][]	_transitionMatrix Initial guess array for the state transition matrix for the Alpha-Beta Recursion.
Parameter	A0 The user-provided initial guess of the transition probability matrix.
Parameter	batchSize The user-provided batch-size to be considered in the estimation.
TypedIOPort	input The input port that provides the sample observations.
(package private) double	likelihood
Parameter	likelihoodThreshold The user-provided threshold on the minimum desired improvement on likelihood per iteration.
Parameter	maxIterations The user-provided maximum number of allowed iterations of the Alpha-Beta Recursion.
(package private) java.util.HashMap	newEstimates
Parameter	nStates Number of states of the HMM.
Parameter	priorDistribution The user-provided initial guess on the prior probability distribution.
TypedIOPort	priorEstimates The vector estimate for the prior distribution on the set of states.
Parameter	randomizeGuessVectors Boolean that determines whether or not to randomize input guess vectors.
Parameter	serviceTimeMultiplicationFactor The service time for the default messageLength of 1.
TypedIOPort	transitionMatrix The transition matrix estimate obtained by iterating over the observation set.

Fields inherited from class ptolemy.actor.lib.aspect.AtomicCommunicationAspect

_parameters, _tokenCount

Fields inherited from class ptolemy.actor.TypedAtomicActor

_typesValid

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.CommunicationAspect

decoratorHighlightColorName

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

Constructors

Constructor and Description
ParameterEstimator(CompositeEntity container, java.lang.String name) Construct a Bus with a name and a container.

Method Summary

Modifier and Type	Method and Description
protected abstract boolean	_checkForConvergence(int i)
protected boolean	_EMParameterEstimation()
protected void	_initializeArrays()
protected abstract void	_initializeEMParameters()
protected abstract void	_iterateEM()
protected void	_scheduleRefire() Schedule a refiring of the actor.
protected abstract void	_updateEstimates()
void	attributeChanged(Attribute attribute) If the attribute is serviceTime, then ensure that the value is non-negative.
java.lang.Object	clone(Workspace workspace) Clone this actor into the specified workspace.
DecoratorAttributes	createDecoratorAttributes(NamedObj target) Return the decorated attributes for the target NamedObj.
IntermediateReceiver	createIntermediateReceiver(Receiver receiver) Create an intermediate receiver that wraps a given receiver.
protected abstract double	emissionProbability(double y, int hiddenState)
void	fire() Send first token in the queue to the target receiver.
protected java.util.HashMap	HMMAlphaBetaRecursion(double[] y, double[][] A, double[] prior, int nCategories) Java implementation of the Baum-Welch algorithm (Alpha-Beta Recursion) for parameter estimation and cluster assignment.
protected java.util.HashMap	HMMAlphaBetaRecursionNonNormalized(double[] y, double[][] A, double[] prior, int unused)
void	initialize() Initialize the actor.
boolean	postfire() If there are still tokens in the queue and a token has been produced in the fire, schedule a refiring.
void	reset() Nothing to do.
void	sendToken(Receiver source, Receiver receiver, Token token) Initiate a send of the specified token to the specified receiver.
void	setContainer(CompositeEntity container) Override the base class to first set the container, then establish a connection with any decorated objects it finds in scope in the new container.

Methods inherited from class ptolemy.actor.lib.aspect.AtomicCommunicationAspect

_sendToReceiver, decoratedObjects, isGlobalDecorator, registerListener, sendCommunicationEvent

Methods inherited from class ptolemy.actor.TypedAtomicActor

_containedTypeConstraints, _customTypeConstraints, _defaultTypeConstraints, _fireAt, _fireAt, attributeTypeChanged, clone, isBackwardTypeInferenceEnabled, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, _declareDelayDependency, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, stop, stopFire, terminate, wrapup

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_addPort, _description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

serviceTimeMultiplicationFactor

public Parameter serviceTimeMultiplicationFactor

The service time for the default messageLength of 1. This is a double with default 0.1. It is required to be positive.

A0

public Parameter A0

The user-provided initial guess of the transition probability matrix.

likelihoodThreshold

public Parameter likelihoodThreshold

The user-provided threshold on the minimum desired improvement on likelihood per iteration.

maxIterations

public Parameter maxIterations

The user-provided maximum number of allowed iterations of the Alpha-Beta Recursion.

batchSize

public Parameter batchSize

The user-provided batch-size to be considered in the estimation.

nStates

public Parameter nStates

Number of states of the HMM.

randomizeGuessVectors

public Parameter randomizeGuessVectors

Boolean that determines whether or not to randomize input guess vectors.

priorDistribution

public Parameter priorDistribution

The user-provided initial guess on the prior probability distribution.

input

public TypedIOPort input

The input port that provides the sample observations.

priorEstimates

public TypedIOPort priorEstimates

The vector estimate for the prior distribution on the set of states.

transitionMatrix

public TypedIOPort transitionMatrix

The transition matrix estimate obtained by iterating over the observation set.

_A0

protected double[][] _A0

User-defined initial guess array for the state transition matrix.

_batchSize

protected int _batchSize

User-defined batch size.

_likelihood

protected double _likelihood

The likelihood value of the observations given the current estimates L(x1,....xT | \theta_p).

_likelihoodThreshold

protected double _likelihoodThreshold

The likelihood threshold.

_nIterations

protected int _nIterations

User-defined number of iterations of the alpha-beta recursion.

_nStates

protected int _nStates

Number of hidden states in the model.

_observations

protected double[] _observations

Observation array.

_observedTokens

protected java.util.HashMap<java.lang.String,java.util.List<java.lang.Double>> _observedTokens

The observation tokens.

_priors

protected double[] _priors

Prior distribution on hidden states.

_priorIn

protected double[] _priorIn

The prior estimates used in the EM iterations

_randomize

protected boolean _randomize

If true, then randomize the initial guess vectors.

_transitionMatrix

protected double[][] _transitionMatrix

Initial guess array for the state transition matrix for the Alpha-Beta Recursion.

newEstimates

java.util.HashMap newEstimates

likelihood

double likelihood

Constructor Detail

ParameterEstimator

public ParameterEstimator(CompositeEntity container,
                          java.lang.String name)
                   throws IllegalActionException,
                          NameDuplicationException

Construct a Bus with a name and a container. The container argument must not be null, or a NullPointerException will be thrown. This actor will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version of the workspace.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the container is incompatible with this actor.

NameDuplicationException - If the name coincides with an actor already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the attribute is serviceTime, then ensure that the value is non-negative.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the service time is negative.

createDecoratorAttributes

public DecoratorAttributes createDecoratorAttributes(NamedObj target)

Return the decorated attributes for the target NamedObj. If the specified target is not an Actor, return null.

Specified by:

createDecoratorAttributes in interface Decorator

Overrides:

createDecoratorAttributes in class AtomicCommunicationAspect

Parameters:

target - The NamedObj that will be decorated.

Returns:

The decorated attributes for the target NamedObj, or null if the specified target is not an Actor.

createIntermediateReceiver

public IntermediateReceiver createIntermediateReceiver(Receiver receiver)
                                                throws IllegalActionException

Create an intermediate receiver that wraps a given receiver.

Specified by:

createIntermediateReceiver in interface CommunicationAspect

Overrides:

createIntermediateReceiver in class AtomicCommunicationAspect

Parameters:

receiver - The receiver that is being wrapped.

Returns:

A new intermediate receiver.

Throws:

IllegalActionException - Thrown if Bus is used in container different from the container of the bus.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone this actor into the specified workspace. The new actor is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new actor with the same ports as the original, but no connections and no container. A container must be set before much can be done with this actor.

Overrides:

clone in class AtomicCommunicationAspect

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new Bus.

Throws:

java.lang.CloneNotSupportedException - If cloned ports cannot have as their container the cloned entity (this should not occur), or if one of the attributes cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

fire

public void fire()
          throws IllegalActionException

Send first token in the queue to the target receiver.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - Not thrown in this base class.

initialize

public void initialize()
                throws IllegalActionException

Initialize the actor.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicCommunicationAspect

Throws:

IllegalActionException - If the superclass throws it.

postfire

public boolean postfire()
                 throws IllegalActionException

If there are still tokens in the queue and a token has been produced in the fire, schedule a refiring.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor<TypedIOPort>

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - Not thrown in this base class.

sendToken

public void sendToken(Receiver source,
                      Receiver receiver,
                      Token token)
               throws IllegalActionException

Initiate a send of the specified token to the specified receiver. This method will schedule a refiring of this actor if there is not one already scheduled.

Parameters:

source - Sender of the token.

receiver - The receiver to send to.

token - The token to send.

Throws:

IllegalActionException - If the refiring request fails.

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to first set the container, then establish a connection with any decorated objects it finds in scope in the new container.

Overrides:

setContainer in class AtomicCommunicationAspect

Parameters:

container - The container to attach this attribute to..

Throws:

IllegalActionException - If this attribute is not of the expected class for the container, or it has no name, or the attribute and container are not in the same workspace, or the proposed container would result in recursive containment.

NameDuplicationException - If the container already has an attribute with the name of this attribute.

See Also:

ComponentEntity.getContainer()

reset

public void reset()

Nothing to do.

_EMParameterEstimation

protected boolean _EMParameterEstimation()

emissionProbability

protected abstract double emissionProbability(double y,
                                              int hiddenState)

_initializeArrays

protected void _initializeArrays()
                          throws IllegalActionException

Throws:

IllegalActionException

_initializeEMParameters

protected abstract void _initializeEMParameters()

_iterateEM

protected abstract void _iterateEM()

_checkForConvergence

protected abstract boolean _checkForConvergence(int i)

_scheduleRefire

protected void _scheduleRefire()
                        throws IllegalActionException

Schedule a refiring of the actor.

Throws:

IllegalActionException - Thrown if the actor cannot be rescheduled

_updateEstimates

protected abstract void _updateEstimates()

HMMAlphaBetaRecursion

protected java.util.HashMap HMMAlphaBetaRecursion(double[] y,
                                                  double[][] A,
                                                  double[] prior,
                                                  int nCategories)

Java implementation of the Baum-Welch algorithm (Alpha-Beta Recursion) for parameter estimation and cluster assignment. This method uses normalized alpha values for computing the conditional probabilities of input sequences, to ensure numerical stability. Set nCategories to zero for continuous distribution types

Parameters:

y - y values

A - A values

prior - prior values

nCategories - The number of categories

Returns:

a hashmaps with String keys and double array values.

HMMAlphaBetaRecursionNonNormalized

protected java.util.HashMap HMMAlphaBetaRecursionNonNormalized(double[] y,
                                                               double[][] A,
                                                               double[] prior,
                                                               int unused)