com.agenarisk.api.model

Class Node

java.lang.Object

com.agenarisk.api.model.Node

All Implemented Interfaces:

Identifiable<NodeException>, Named, Networked<Node>, Storable, Comparable<Node>

public class Node
extends Object
implements Networked<Node>, Comparable<Node>, Identifiable<NodeException>, Storable, Named

Node class represents a node in the Network.

Author:

Eugene Dementiev

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Node.Field This is set of fields for input/output to XML and JSON format
static class	Node.Type These are Node types that correspond to AgenaRisk Desktop node types

Method Summary

Modifier and Type	Method and Description
protected boolean	addLink(Link link) Removes the Link object from the linksOut list.
int	compareTo(Node o) Compares this Node object to another based on the Id of this object.
boolean	convertToSimulated() Enables calculation simulation for the Node (only possible for ContinuousInterval or IntegerInterval nodes).
boolean	convertToStatic(DataSet dataSet) Disables simulation and converts dynamic states from the results of the provided DataSet into static permanent states. Any VariableObservations in the DataSet will replace current Node variable defaults and will be replaced from the DataSet observations.
protected static Node	createNode(Network network, org.json.JSONObject jsonNode) Factory method to create a Node for use by the Network class.
protected static Node	createNode(Network network, org.json.JSONObject jsonNode, boolean withTables) Factory method to create a Node for use by the Network class.
protected static Node	createNode(Network network, String id, String name, Node.Type type) Factory method to be called by a Network object that is trying to add a Node to itself.
Variable	createVariable(String varName, double defaultValue) Creates a new node Variable.
boolean	equals(Object obj) Checks equality of a given object to this Node.
List<String>	getAllowedFunctionTokens() Returns a list of parent IDs, variable names etc to use as parseable function tokens.
Set<Node>	getAncestors() Builds and returns a set of ancestors for this Node. Does not include itself. Does not follow cross-network links (only includes Nodes in the same Network).
Set<Node>	getChildren() Builds and returns a set of Node's children, which is valid at the time of request.
Set<Node>	getDescendants() Builds and returns a set of descendants for this Node. Does not include itself. Does not follow cross-network links (only includes Nodes in the same Network).
String	getDescription() Gets the description of this node
String	getId() Gets the ID of this Node.
List<Link>	getLinksIn() Returns a copy of the list of incoming Links.
List<Link>	getLinksOut() Returns a copy of the list of outgoing Links.
uk.co.agena.minerva.model.extendedbn.ExtendedNode	getLogicNode() Returns the underlying ExtendedNode.
String	getName() Gets the name of this node.
Network	getNetwork() Returns the Network containing this Node.
Set<Node>	getParents() Builds and returns a set of Node's parents, which is valid at the time of request.
State	getState(String label) Find a state by given label in this Node's underlying logic node.
List<State>	getStates() Returns a representation of Node's states at the time of the request. The list will not be updated to reflect any changes, and no changes to the list or the States will be reflected in the Model.
NodeConfiguration.TableType	getTableType() Returns the type of the table configured for the Node. Possible values are: • Manual • Expression • Partitioned
Node.Type	getType() Gets the Type of this Node.
Variable	getVariable(String varName) Retrieves and returns the Variable by name.
List<Variable>	getVariables() Gets an unmodifiable list of all Variables. Will not reflect Variables being added or deleted from the Node.
int	hashCode() Returns a hash code value for this object.
boolean	isConnectedInput() Returns true if this Node has an incoming link from another Network.
boolean	isConnectedOutput() Returns true if this Node has an outgoing link to another Network.
boolean	isNumericInterval() Returns true if the Node is continuous or integer interval
boolean	isSimulated() Returns true if the Node is simulated and false otherwise.
Link	linkFrom(Node parent) Creates a simple Link from the given Node to this Node in the same Network.
static void	linkNodes(Model model, org.json.JSONArray jsonLinks) Creates links from the given JSON.
static Link	linkNodes(Node fromNode, Node toNode) Creates a simple Link between two nodes in the same Network.
static Link	linkNodes(Node fromNode, Node toNode, CrossNetworkLink.Type type) Creates a Link between two nodes in same or different Networks.
static Link	linkNodes(Node fromNode, Node toNode, CrossNetworkLink.Type type, String stateToPass) Creates a Link between two nodes in same or different Networks.
Link	linkTo(Node child) Creates a simple Link from this Node to given Node in the same Network.
protected uk.co.agena.minerva.model.extendedbn.ExtendedNodeFunction	parseAsFunction(String expression, List<String> allowedTokens, boolean relaxFunctionRequirements) Parses the provided expression as an ExtendedNodeFunction
void	partitionByParents(List<Node> partitionParents) Sets node partitions based on the parent states.
protected boolean	removeLink(Link link) Removes the Link object from the linksOut list.
void	removeVariable(String varName) Removes Variable by name if it exists
void	resetTable() Attempts to reset node's table
void	setDescription(String description) Sets the description of this Node.
void	setId(String newId) Changes the ID of this Node to the provided ID, if the new ID is not already taken.
protected void	setLogicNode(uk.co.agena.minerva.model.extendedbn.ExtendedNode logicNode) Links this Node to an underlying Minerva Node object.
void	setName(String name) Sets the name of this Node.
void	setStates(org.json.JSONArray jsonStates) Replaces Node's states by the ones given in the JSON array.
void	setStates(List<String> states) Replaces Node's states by the ones given in the array.
void	setStates(String[] states) Replaces Node's states by the ones given in the array.
void	setTable(org.json.JSONObject jsonTable) Replaces the Node's probability table with one specified in the given JSON.
void	setTableColumns(double[][] columns) Sets the manual NPT according to columns provided.
void	setTableFunction(String expression) Sets Node function to the one provided.
void	setTableFunction(String expression, List<String> allowedTokens) Sets Node function to the one provided.
protected void	setTableFunction(String expression, List<String> allowedTokens, boolean relaxFunctionRequirements) Sets Node function to the one provided.
void	setTableFunctions(List<String> expressions, List<Node> partitionParents) Sets Node expressions to the ones provided.
protected void	setTableFunctions(List<String> expressions, List<String> allowedTokens, boolean relaxFunctionRequirements, List<Node> partitionParents) Sets Node expressions to the ones provided.
void	setTableRows(double[][] rows) Sets the manual NPT according to rows provided.
boolean	setTableUniform() Resets the node NPT to a uniform table.
org.json.JSONObject	toJson() Creates a JSON representing this Node, ready for file storage.
String	toString() Returns JSON equivalent of this Node as a String.
String	toStringExtra() Returns `network`.`node` String representing this Node.
boolean	unlink(Node linkedNode) Removes a link between this Node and the linkedNode, if such link exists.
static boolean	unlinkNodes(Node node1, Node node2) Checks that there is a Link between two nodes and destroys it.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.agenarisk.api.model.interfaces.Networked

hasAncestor, hasDescendant

Method Detail

getLinksIn

public List<Link> getLinksIn()

Returns a copy of the list of incoming Links. The membership is only guaranteed to be valid at the time of request and is not maintained.

Specified by:

getLinksIn in interface Networked<Node>

Returns:

list of incoming Links

getLinksOut

public List<Link> getLinksOut()

Returns a copy of the list of outgoing Links. The membership is only guaranteed to be valid at the time of request and is not maintained.

Specified by:

getLinksOut in interface Networked<Node>

Returns:

list of outgoing Links

getParents

public Set<Node> getParents()

Builds and returns a set of Node's parents, which is valid at the time of request. This set will not reflect any membership changes made afterwards.

Specified by:

getParents in interface Networked<Node>

Returns:

a set of Node's parents

getChildren

public Set<Node> getChildren()

Builds and returns a set of Node's children, which is valid at the time of request. This set will not reflect any membership changes made afterwards.

Specified by:

getChildren in interface Networked<Node>

Returns:

a set of Node's children

addLink

protected final boolean addLink(Link link)

Removes the Link object from the linksOut list.

Parameters:

link - the Link to remove

Returns:

true if Link was added and false if the Link does not concern this Node

removeLink

protected final boolean removeLink(Link link)

Removes the Link object from the linksOut list.

Parameters:

link - the Link to remove

Returns:

true if Link was removed and false if the Link does not concern this Node

linkTo

public Link linkTo(Node child)
            throws LinkException

Creates a simple Link from this Node to given Node in the same Network.
If child table is in Manual mode, this action will reset it to a uniform table.

Parameters:

child - the child Node

Returns:

created Link

Throws:

LinkException - if Link already exists, or a cross network link is being created (use Node.linkNodes() for that instead)

linkFrom

public Link linkFrom(Node parent)
              throws LinkException

Creates a simple Link from the given Node to this Node in the same Network.
If this Node's table is in Manual mode, this action will reset it to a uniform table.

Parameters:

parent - the parent Node

Returns:

created Link

Throws:

LinkException - if Link already exists, or a cross network link is being created (use Node.linkNodes() for that instead)

unlinkNodes

public static boolean unlinkNodes(Node node1,
                                  Node node2)

Checks that there is a Link between two nodes and destroys it. No effect if there is no link between these two nodes.

Parameters:

node1 - Node 1

node2 - Node 2

Returns:

true if the link was destroyed, false if there was no link

linkNodes

public static void linkNodes(Model model,
                             org.json.JSONArray jsonLinks)
                      throws org.json.JSONException,
                             LinkException,
                             NodeException

Creates links from the given JSON.
Does nothing if JSON is null or empty.

Parameters:

model - the model to create Links in

jsonLinks - configuration of the Links

Throws:

org.json.JSONException - if JSON structure is invalid or inconsistent

LinkException - if a Link fails to be created

NodeException - if failed to create a link between nodes

linkNodes

public static Link linkNodes(Node fromNode,
                             Node toNode)
                      throws LinkException

Creates a simple Link between two nodes in the same Network.

Parameters:

fromNode - Node to link from

toNode - Node to link to

Returns:

created Link

Throws:

LinkException - if Link already exists, or a cross network link is being created

linkNodes

public static Link linkNodes(Node fromNode,
                             Node toNode,
                             CrossNetworkLink.Type type)
                      throws LinkException

Creates a Link between two nodes in same or different Networks.

Parameters:

fromNode - Node to link from

toNode - Node to link to

type - type of CrossNetworkLink if applicable

Returns:

created Link

Throws:

LinkException - if Link already exists, or a cross network link is being created with invalid arguments

linkNodes

public static Link linkNodes(Node fromNode,
                             Node toNode,
                             CrossNetworkLink.Type type,
                             String stateToPass)
                      throws LinkException

Creates a Link between two nodes in same or different Networks.
The underlying NPT of the child node will be reset to some default value.

Parameters:

fromNode - Node to link from

toNode - Node to link to

type - type of CrossNetworkLink if applicable

stateToPass - if type is State, this specifies the state to pass

Returns:

created Link

Throws:

LinkException - if Link already exists, or a cross network link is being created with invalid arguments

createNode

protected static Node createNode(Network network,
                                 String id,
                                 String name,
                                 Node.Type type)

Factory method to be called by a Network object that is trying to add a Node to itself.

Parameters:

network - the network to add a node to

id - the ID of the node

name - the name of the node

type - type of the Node to create

Returns:

the created Node

createNode

protected static Node createNode(Network network,
                                 org.json.JSONObject jsonNode)
                          throws NodeException,
                                 org.json.JSONException

Factory method to create a Node for use by the Network class.
Creates the underlying logic objects.
Note: loading tables will fail if parent nodes do not exist in the model. In that case load all nodes first without tables and then use setTable(JSONObject) after all nodes, states, intra and cross network links had been created.

Parameters:

network - Network that the Node will be added to

jsonNode - configuration of the Node

Returns:

created Node

Throws:

NodeException - if failed to create the node

org.json.JSONException - if JSON configuration is incomplete or invalid

See Also:

setTable(JSONObject)

createNode

protected static Node createNode(Network network,
                                 org.json.JSONObject jsonNode,
                                 boolean withTables)
                          throws NodeException,
                                 org.json.JSONException

Factory method to create a Node for use by the Network class.
Creates the underlying logic objects.
Note: loading tables will fail if parent nodes do not exist in the model. In that case load all nodes first without tables and then use setTable(JSONObject) after all nodes, states, intra and cross network links had been created.

Parameters:

network - Network that the Node will be added to

jsonNode - configuration of the Node

withTables - whether to load node tables from JSON

Returns:

created Node

Throws:

NodeException - if failed to create the node

org.json.JSONException - if JSON configuration is incomplete or invalid

See Also:

setTable(JSONObject)

setTableColumns

public void setTableColumns(double[][] columns)
                     throws NodeException

Sets the manual NPT according to columns provided.

Parameters:

columns - 2D array where first dimension are the columns and second dimension are the cells

Throws:

NodeException - if provided table size is wrong or Node does not allow manual NPT

setTableRows

public void setTableRows(double[][] rows)
                  throws NodeException

Sets the manual NPT according to rows provided.

Parameters:

rows - 2D array where first dimension are the rows and second dimension are the cells

Throws:

NodeException - if provided table size is wrong or Node does not allow manual NPT

setTableUniform

public final boolean setTableUniform()

Resets the node NPT to a uniform table.

Returns:

false if operation failed, true otherwise

resetTable

public void resetTable()
                throws NodeException

Attempts to reset node's table

Throws:

NodeException - upon failure

setTable

public void setTable(org.json.JSONObject jsonTable)
              throws NodeException

Replaces the Node's probability table with one specified in the given JSON.
This must be used after all parents states and incoming links had been created.

Parameters:

jsonTable - configuration of the table in JSON format

Throws:

NodeException - if:
∙ table type does not match the rest of the table configuration
∙ table is not a square matrix
∙ the number of cells does not match the number of partitions created by the combination of parent states

setTableFunction

public void setTableFunction(String expression)
                      throws NodeException

Sets Node function to the one provided. Will use node parent IDs and expression variables as allowed tokens.
Resets Node table partitioning and sets Table type to NodeConfiguration.TableType.Expression.

Parameters:

expression - function to set

Throws:

NodeException - if function is invalid

getAllowedFunctionTokens

public List<String> getAllowedFunctionTokens()

Returns a list of parent IDs, variable names etc to use as parseable function tokens.

Returns:

list of allowed function tokens for this node

setTableFunction

public void setTableFunction(String expression,
                             List<String> allowedTokens)
                      throws NodeException

Sets Node function to the one provided.
Resets Node table partitioning and sets Table type to NodeConfiguration.TableType.Expression.

Parameters:

expression - function to set

allowedTokens - list of parent IDs, variable names etc to add as parseable tokens; if null, all tokens are allowed

Throws:

NodeException - if function is invalid

setTableFunction

protected void setTableFunction(String expression,
                                List<String> allowedTokens,
                                boolean relaxFunctionRequirements)
                         throws NodeException

Sets Node function to the one provided.
Resets Node table partitioning and sets Table type to NodeConfiguration.TableType.Expression.

Parameters:

expression - function to set

allowedTokens - list of parent IDs, variable names etc to add as parseable tokens; if null, all tokens are allowed

relaxFunctionRequirements - if true, all function requirements are lifted and any number of arguments are allowed

Throws:

NodeException - if function is invalid

parseAsFunction

protected uk.co.agena.minerva.model.extendedbn.ExtendedNodeFunction parseAsFunction(String expression,
                                                                                    List<String> allowedTokens,
                                                                                    boolean relaxFunctionRequirements)

Parses the provided expression as an ExtendedNodeFunction

Parameters:

expression - function to set

allowedTokens - list of parent IDs, variable names etc to add as parseable tokens; if null, all tokens are allowed

relaxFunctionRequirements - if true, all function requirements are lifted and any number of arguments are allowed

Returns:

ExtendedNodeFunction parsed from the provided expression

setTableFunctions

public void setTableFunctions(List<String> expressions,
                              List<Node> partitionParents)
                       throws NodeException

Sets Node expressions to the ones provided.
Table type will be set to NodeConfiguration.TableType.Partitioned or NodeConfiguration.TableType.Function depending on how many expressions were provided.
If the node only has one non-simulated parent, this parent will be automatically used to partition this node. Otherwise partitions must have been set beforehand using partitionByParents(java.util.List)

Parameters:

expressions - expressions to set

partitionParents - discrete parents to partition by

Throws:

NodeException - if a function is invalid

setTableFunctions

protected void setTableFunctions(List<String> expressions,
                                 List<String> allowedTokens,
                                 boolean relaxFunctionRequirements,
                                 List<Node> partitionParents)
                          throws NodeException

Sets Node expressions to the ones provided.
Table type will be set to NodeConfiguration.TableType.Partitioned or NodeConfiguration.TableType.Function depending on how many expressions were provided.

Parameters:

expressions - expressions to set

allowedTokens - list of parent IDs, variable names etc to add as parseable tokens; if null, all tokens are allowed

relaxFunctionRequirements - if true, all function requirements are lifted and any number of arguments are allowed

partitionParents - discrete parents to partition by, ignored if null or empty

Throws:

NodeException - if a function is invalid

partitionByParents

public void partitionByParents(List<Node> partitionParents)
                        throws NodeException

Sets node partitions based on the parent states.
Order of partitions will be based on the order of nodes in the array and states within them.

Parameters:

partitionParents - parents to partition by

Throws:

NodeException - if one of the nodes in partitionParents is simulated or is not a parent of this Node

setStates

public void setStates(String[] states)
               throws NodeException

Replaces Node's states by the ones given in the array.
This action resets the probability table to uniform.

Parameters:

states - new Node's states

Throws:

NodeException - if state is an invalid range; or if the Node is simulated

setStates

public void setStates(List<String> states)
               throws NodeException

Replaces Node's states by the ones given in the array.
This action resets the probability table to uniform.

Parameters:

states - new Node's states

Throws:

NodeException - if state is an invalid range; or if the Node is simulated

setStates

public void setStates(org.json.JSONArray jsonStates)
               throws NodeException

Replaces Node's states by the ones given in the JSON array.
If null or empty array are provided, no changes are made.
This action resets the probability table to uniform.

Parameters:

jsonStates - new Node's states

Throws:

NodeException - if state is an invalid range; or if the Node is simulated

convertToSimulated

public boolean convertToSimulated()
                           throws NodeException

Enables calculation simulation for the Node (only possible for ContinuousInterval or IntegerInterval nodes).
All current states will be replaced by dynamic states.

Returns:

true if action was performed, false if no action was permitted or required

Throws:

NodeException

convertToStatic

public boolean convertToStatic(DataSet dataSet)
                        throws NodeException

Disables simulation and converts dynamic states from the results of the provided DataSet into static permanent states.
Any VariableObservations in the DataSet will replace current Node variable defaults and will be replaced from the DataSet observations.

Parameters:

dataSet - DataSet to use for creating static states from results

Returns:

true if action was performed, false if no action was permitted or required

Throws:

NodeException - if states could not be created from the DataSet results

isSimulated

public boolean isSimulated()

Returns true if the Node is simulated and false otherwise.

Returns:

true if the Node is simulated and false otherwise

isNumericInterval

public boolean isNumericInterval()

Returns true if the Node is continuous or integer interval

Returns:

true if the Node is continuous or integer interval

toString

public String toString()

Returns JSON equivalent of this Node as a String.

Overrides:

toString in class Object

Returns:

String version of this Node

toStringExtra

public String toStringExtra()

Returns `network`.`node` String representing this Node.

Returns:

detailed String representing this Node

getNetwork

public Network getNetwork()

Returns the Network containing this Node.
Using logic objects directly is unsafe and is likely to break something.

Returns:

the Network containing this Node

getLogicNode

public uk.co.agena.minerva.model.extendedbn.ExtendedNode getLogicNode()

Returns the underlying ExtendedNode.

Returns:

the underlying ExtendedNode

getId

public String getId()

Gets the ID of this Node.

Specified by:

getId in interface Identifiable<NodeException>

Returns:

the ID of this Node

setId

public void setId(String newId)
           throws NodeException

Changes the ID of this Node to the provided ID, if the new ID is not already taken.
Will lock IDContainer.class while doing so.

Specified by:

setId in interface Identifiable<NodeException>

Parameters:

newId - the new ID

Throws:

NodeException - if fails to change ID

setName

public void setName(String name)

Sets the name of this Node.

Specified by:

setName in interface Named

Parameters:

name - new name

getName

public String getName()

Gets the name of this node.

Specified by:

getName in interface Named

Returns:

the name of this node

setDescription

public void setDescription(String description)

Sets the description of this Node.

Specified by:

setDescription in interface Named

Parameters:

description - new description

getDescription

public String getDescription()

Gets the description of this node

Specified by:

getDescription in interface Named

Returns:

the description of this node

compareTo

public int compareTo(Node o)

Compares this Node object to another based on the Id of this object.

Specified by:

compareTo in interface Comparable<Node>

Parameters:

o - another Node object

Returns:

a negative integer, zero, or a positive integer if the value of this object's ID precedes the one of the specified object's ID

equals

public boolean equals(Object obj)

Checks equality of a given object to this Node. Returns true if logic nodes of both objects are the same.

Overrides:

equals in class Object

Parameters:

obj - The object to compare this Node against

Returns:

true if the given object represents the same Node as this Node, false otherwise

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

unlink

public boolean unlink(Node linkedNode)

Removes a link between this Node and the linkedNode, if such link exists.
Will check incoming and outgoing Links
Both Nodes will no longer refer to each other

Specified by:

unlink in interface Networked<Node>

Parameters:

linkedNode - the Node to break Link with

Returns:

false if there was no Link; or true if the Link was removed

toJson

public org.json.JSONObject toJson()

Creates a JSON representing this Node, ready for file storage.

Specified by:

toJson in interface Storable

Returns:

JSONObject representing this Node

getState

public State getState(String label)

Find a state by given label in this Node's underlying logic node.

Parameters:

label - label of the required state

Returns:

state with given label or null if such state does not exist

getStates

public List<State> getStates()

Returns a representation of Node's states at the time of the request.
The list will not be updated to reflect any changes, and no changes to the list or the States will be reflected in the Model.

Returns:

representation of Node's states

getType

public Node.Type getType()

Gets the Type of this Node.

Returns:

Type of this Node

setLogicNode

protected void setLogicNode(uk.co.agena.minerva.model.extendedbn.ExtendedNode logicNode)

Links this Node to an underlying Minerva Node object. Should only be used while wrapping a new Model around the Minerva Model.

Parameters:

logicNode - the logical node

getTableType

public NodeConfiguration.TableType getTableType()

Returns the type of the table configured for the Node.
Possible values are:
• Manual
• Expression
• Partitioned

Returns:

table type of the Node

isConnectedInput

public boolean isConnectedInput()

Returns true if this Node has an incoming link from another Network.

Returns:

true if this Node has an incoming link from another Network

isConnectedOutput

public boolean isConnectedOutput()

Returns true if this Node has an outgoing link to another Network.

Returns:

true if this Node has an outgoing link to another Network

getAncestors

public Set<Node> getAncestors()

Builds and returns a set of ancestors for this Node.
Does not include itself.
Does not follow cross-network links (only includes Nodes in the same Network).

Returns:

HashSet of ancestors for this Node

getDescendants

public Set<Node> getDescendants()

Builds and returns a set of descendants for this Node.
Does not include itself.
Does not follow cross-network links (only includes Nodes in the same Network).

Returns:

HashSet of descendants for this Node

createVariable

public Variable createVariable(String varName,
                               double defaultValue)
                        throws NetworkException

Creates a new node Variable.

Parameters:

varName - unique Variable name, only number, letters and underscores are allowed, but can't be just a number

defaultValue - default value of the Variable

Returns:

the Variable instance created

Throws:

NodeException - if a Variable with this name already exists in this Node

NetworkException

getVariable

public Variable getVariable(String varName)

Retrieves and returns the Variable by name.

Parameters:

varName - name of the Variable to return

Returns:

Variable with provided name or null

removeVariable

public void removeVariable(String varName)

Removes Variable by name if it exists

Parameters:

varName - name of the Variable to remove

getVariables

public List<Variable> getVariables()

Gets an unmodifiable list of all Variables.
Will not reflect Variables being added or deleted from the Node.

Returns:

unmodifiable list of all Variables