com.agenarisk.api.model

Class Model

java.lang.Object

com.agenarisk.api.model.Model

All Implemented Interfaces:

IdContainer<ModelException>, Storable

public class Model
extends Object
implements IdContainer<ModelException>, Storable

Model class represents an AgenaRisk model that may contain a number of Bayesian networks, datasets etc, equivalent to com.agenarisk.api.model.Model in AgenaRisk Java API v1.

Author:

Eugene Dementiev

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Model.CalculationFlag
static class	Model.ExportFlag
static class	Model.Field This is set of fields for input/output to XML and JSON format

Method Summary

Modifier and Type	Method and Description
protected void	absorb(org.json.JSONObject json) Creates all the Model structure from the provided JSONObject.
void	calculate() Triggers propagation in this Model for all Networks and DataSets.
void	calculate(Collection<Network> networks, Collection<DataSet> dataSets, Model.CalculationFlag... flags) Triggers propagation in this model for provided Networks and DataSets. If either is null, all Networks or DataSets will be used instead.
void	convertToStatic(DataSet dataSet) Make all states of dynamically discretized nodes static as they currently are in the provided DataSet. No action will be performed if no nodes are simulated. Any VariableObservations in the DataSet will replace current Node variable defaults and will be replaced from the DataSet observations.
DataSet	createDataSet(org.json.JSONObject jsonDataSet) Creates a DataSet for this Model from JSON data.
DataSet	createDataSet(String id) Creates a new DataSet and adds it to this Model.
Link	createLink(Node source, Node target, CrossNetworkLink.Type type) Creates a Link between two nodes in same or different Networks.
Link	createLink(Node source, Node target, State state) Creates a CrossNetworkLink of type CrossNetworkLink.Type.State that passes the given state from source Node to target Node.
Link	createLink(String sourceNetworkId, String sourceNodeId, String targetNetworkId, String targetNodeId, CrossNetworkLink.Type type) Creates a CrossNetworkLink of given Type.
Link	createLink(String sourceNetworkId, String sourceNodeId, String targetNetworkId, String targetNodeId, String stateLabel) Creates a CrossNetworkLink of type CrossNetworkLink.Type.State that passes the given state from source Node to target Node.
static Model	createModel() Factory method to create an empty instance of a Model class.
static Model	createModel(org.json.JSONObject json) Factory method to create an instance of a Model from provided JSONObject.
static Model	createModel(uk.co.agena.minerva.model.Model api1Model) Creates a Model from a Minerva Model object.
Network	createNetwork(org.json.JSONObject jsonNetwork) Creates a Network and adds it to this Model.
Network	createNetwork(org.json.JSONObject jsonNetwork, boolean withTables) Creates a Network and adds it to this Model.
Network	createNetwork(String id) Creates a new empty Network and adds it to this Model.
Network	createNetwork(String id, String name) Creates a new empty Network and adds it to this Model.
org.json.JSONObject	export(Model.ExportFlag... flags) Returns the Model as a minimal JSON. Keeps only elements essential for a clean calculation.
boolean	factorize() Performs binary factorization on the model if there are any simulation nodes with more than 3 parents. This involves the model being recreated from scratch and all previously held references to pre-existing objects in the Model will become invalid and should be released.
String	getAvailableDataSetId(String prefix) Generates a new DataSet ID that is guaranteed to be available at the return time.
DataSet	getDataSet(String id) Looks up and returns a DataSet by its ID.
List<DataSet>	getDataSetList() Returns DataSets of this Model as a list
Map<String,DataSet>	getDataSets() Returns a copy of ID-Network map.
Map<Id,? extends Identifiable>	getIdMap(Class<? extends Identifiable> idClassType) Deprecated. For internal use only
org.json.JSONObject	getJsonAudit() Returns audit stored as JSON
org.json.JSONObject	getJsonGraphics() Returns model graphics stored as JSON
org.json.JSONArray	getJsonPictures() Returns Risk Map pictures stored as JSON
org.json.JSONArray	getJsonTexts() Returns Risk Map texts stored as JSON
uk.co.agena.minerva.model.Model	getLogicModel() Returns the underlying ExtendedBN.
Network	getNetwork(String id) Looks up and returns a Network by its ID.
List<Network>	getNetworkList() Returns Networks of this Model as a list
Map<String,Network>	getNetworks() Returns a copy of ID-Network map.
Settings	getSettings() Returns Model Settings object.
boolean	isCalculated() Checks whether the model had been successfully calculated and requires no calculation at this time. Model is considered calculated if all Networks had been calculated.
static Model	loadModel(String path) Loads a Model from provided path
protected void	loadQuestionnaire(org.json.JSONObject jsonQstnr) Loads a Questionnaire from JSON
protected void	loadRiskTable(org.json.JSONArray jsonRiskTable) Loads Risk Table from JSON into the current Model
boolean	removeDataSet(DataSet dataSet) Removes the provided DataSet from the model
void	removeNetwork(Network net) Removes provided Network from this Model, breaks any existing links to and from this Network.
void	removeNetwork(String netId) Removes provided Network from this Model, breaks any existing links to and from this Network.
void	reset() Reset the model by removing all Networks, Links, DataSets etc
void	save(String path) Saves the Model to a file path specified. Output format is determined by path extension: • AgenaRisk 7 CMP for "cmp" • XML for "xml" • JSON for everything else
void	saveEssentials(String path, boolean keepMeta) Saves the Model as a light-weight JSON. Keeps only elements essential for a clean calculation. Drops: Graphics, RiskTable, DataSets, compiled non-manual NPTs, names, notes and descriptions.
protected void	setLogicModel(uk.co.agena.minerva.model.Model logicModel) Links this Model to an underlying Minerva Model object.
void	throwIdExistsException(String id) Deprecated. For internal use only
void	throwOldIdNullException(String id) Deprecated. For internal use only
org.json.JSONObject	toJson() Creates a JSON representing this Network, ready for file storage.

Methods inherited from class java.lang.Object

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

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

changeContainedId

Method Detail

loadModel

public static Model loadModel(String path)
                       throws ModelException

Loads a Model from provided path

Parameters:

path - path to model file

Returns:

loaded Model

Throws:

ModelException - if failed to read the file; or if JSON was corrupt or missing required attributes; or if CMP could not be converted to JSON

createModel

public static Model createModel()

Factory method to create an empty instance of a Model class.

Returns:

new instance of a Model

createModel

public static Model createModel(uk.co.agena.minerva.model.Model api1Model)
                         throws ModelException

Creates a Model from a Minerva Model object.

Parameters:

api1Model - the logical Minerva Model

Returns:

Model object with the provided Minerva Model underneath

Throws:

ModelException - if Minerva Model fails to be converted to JSON

createModel

public static Model createModel(org.json.JSONObject json)
                         throws ModelException,
                                org.json.JSONException

Factory method to create an instance of a Model from provided JSONObject.
Creates all member components.
If a DataSet with the provided ID already exists, it will append a number to that ID to make it unique.
If an observation in DataSet fails to be set, it is ignored and results for that DataSet are not loaded.

Parameters:

json - JSONObject representing this model, including structure, tables, graphics etc

Returns:

Model created Model

Throws:

ModelException - if failed to create any of the components

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

absorb

protected void absorb(org.json.JSONObject json)
               throws ModelException,
                      org.json.JSONException

Creates all the Model structure from the provided JSONObject.
Creates all member components.
If a DataSet with the provided ID already exists, it will append a number to that ID to make it unique.
If an observation in DataSet fails to be set, it is ignored and results for that DataSet are not loaded.

Parameters:

json - JSONObject representing this model, including structure, tables, graphics etc

Throws:

ModelException - if failed to create any of the components

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

createNetwork

public Network createNetwork(org.json.JSONObject jsonNetwork)
                      throws NetworkException

Creates a Network and adds it to this Model.
Creates all member components.
Note: loading node 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:

jsonNetwork - JSONObject representing the network, including structure, tables, graphics etc

Returns:

Network object

Throws:

NetworkException - if failed to create the Network

See Also:

Node.setTable(JSONObject)

createNetwork

public Network createNetwork(org.json.JSONObject jsonNetwork,
                             boolean withTables)
                      throws NetworkException

Creates a Network and adds it to this Model.
Creates all member components.
Note: loading node 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:

jsonNetwork - JSONObject representing the network, including structure, tables, graphics etc

withTables - whether to load node tables from JSON

Returns:

Network object

Throws:

NetworkException - if failed to create the Network

See Also:

Node.setTable(JSONObject)

createNetwork

public Network createNetwork(String id)
                      throws NetworkException

Creates a new empty Network and adds it to this Model.

Parameters:

id - unique ID of the Network

Returns:

the Network instance added to this Model

Throws:

NetworkException - if a Network with this ID already exists

createNetwork

public Network createNetwork(String id,
                             String name)
                      throws NetworkException

Creates a new empty Network and adds it to this Model.

Parameters:

id - unique ID of the Network

name - non-unique name of the Network

Returns:

the Network instance added to this Model

Throws:

NetworkException - if a Network with this ID already exists

removeNetwork

public void removeNetwork(Network net)

Removes provided Network from this Model, breaks any existing links to and from this Network.

Parameters:

net - Network to remove

removeNetwork

public void removeNetwork(String netId)

Removes provided Network from this Model, breaks any existing links to and from this Network.

Parameters:

netId - ID of the Network to remove

toJson

public org.json.JSONObject toJson()

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

Specified by:

toJson in interface Storable

Returns:

JSONObject representing this Network

Throws:

AgenaRiskRuntimeException - if failed to convert model to JSON

getIdMap

@Deprecated
public Map<Id,? extends Identifiable> getIdMap(Class<? extends Identifiable> idClassType)
                                                     throws ModelException

Deprecated. For internal use only

Description copied from interface: IdContainer

Returns the map of identifiable items based on.

Specified by:

getIdMap in interface IdContainer<ModelException>

Parameters:

idClassType - the class of identifiable object

Returns:

ID-Identifiable map

Throws:

ModelException - when invalid type requested

throwIdExistsException

@Deprecated
public void throwIdExistsException(String id)
                                         throws ModelException

Deprecated. For internal use only

Description copied from interface: IdContainer

Throws an Exception with message e.g. "Object with id `id` already exists", localised for the implementing class.

Specified by:

throwIdExistsException in interface IdContainer<ModelException>

Parameters:

id - ID of the existing object

Throws:

ModelException - when invoked

throwOldIdNullException

@Deprecated
public void throwOldIdNullException(String id)
                                          throws ModelException

Deprecated. For internal use only

Description copied from interface: IdContainer

Throws an Exception with message e.g. "No such object or old ID is null", localised for the implementing class.

Specified by:

throwOldIdNullException in interface IdContainer<ModelException>

Parameters:

id - ID of the existing object

Throws:

ModelException - when invoked

getNetwork

public Network getNetwork(String id)

Looks up and returns a Network by its ID.

Parameters:

id - the ID of the Network to return

Returns:

the Network identified by ID or null, if no such Network exists in this Model

getNetworks

public Map<String,Network> getNetworks()

Returns a copy of ID-Network map. Once generated, membership of this map is not maintained.

Returns:

copy of ID-Network map

getNetworkList

public List<Network> getNetworkList()

Returns Networks of this Model as a list

Returns:

list of Networks

getLogicModel

public uk.co.agena.minerva.model.Model getLogicModel()

Returns the underlying ExtendedBN.
Using logic objects directly is unsafe and is likely to break something.

Returns:

the underlying ExtendedBN

calculate

public void calculate()
               throws CalculationException

Triggers propagation in this Model for all Networks and DataSets.

Throws:

CalculationException - if calculation failed

InconsistentEvidenceException - specifically in case inconsistent evidence was detected

calculate

public void calculate(Collection<Network> networks,
                      Collection<DataSet> dataSets,
                      Model.CalculationFlag... flags)
               throws CalculationException

Triggers propagation in this model for provided Networks and DataSets.
If either is null, all Networks or DataSets will be used instead.

Parameters:

networks - Networks to calculate, can be null for all Networks

dataSets - DataSets to calculate, can be null for all DataSets

flags - Calculation flags

Throws:

CalculationException - if calculation failed

InconsistentEvidenceException - specifically in case inconsistent evidence was detected

save

public void save(String path)
          throws FileIOException

Saves the Model to a file path specified.
Output format is determined by path extension:
• AgenaRisk 7 CMP for "cmp"
• XML for "xml"
• JSON for everything else

Parameters:

path - the file path to save to

Throws:

FileIOException - if saving fails

export

public org.json.JSONObject export(Model.ExportFlag... flags)
                           throws AdapterException

Returns the Model as a minimal JSON.
Keeps only elements essential for a clean calculation.

Parameters:

flags - flags specifying which attributes to keep

Returns:

minimal JSON

Throws:

AdapterException - if conversion to JSON fails

saveEssentials

public void saveEssentials(String path,
                           boolean keepMeta)
                    throws FileIOException

Saves the Model as a light-weight JSON.
Keeps only elements essential for a clean calculation.
Drops: Graphics, RiskTable, DataSets, compiled non-manual NPTs, names, notes and descriptions.

Parameters:

path - the file path to save to

keepMeta - Keep meta, names, notes and descriptions of Model, Networks and Nodes

Throws:

FileIOException - if saving fails

createDataSet

public DataSet createDataSet(String id)
                      throws DataSetException

Creates a new DataSet and adds it to this Model.

Parameters:

id - unique ID of the DataSet

Returns:

the DataSet instance added to this Model

Throws:

DataSetException - if a DataSet with this ID already exists

loadRiskTable

protected void loadRiskTable(org.json.JSONArray jsonRiskTable)

Loads Risk Table from JSON into the current Model

Parameters:

jsonRiskTable - the Risk Table data

loadQuestionnaire

protected void loadQuestionnaire(org.json.JSONObject jsonQstnr)

Loads a Questionnaire from JSON

Parameters:

jsonQstnr - the Questionnaire data

createDataSet

public DataSet createDataSet(org.json.JSONObject jsonDataSet)
                      throws ModelException

Creates a DataSet for this Model from JSON data.
If a DataSet with the provided ID already exists, it will append a number to that ID to make it unique.
If an observation in DataSet fails to be set, it is ignored and results for that DataSet are not loaded.

Parameters:

jsonDataSet - the JSON data

Returns:

created DataSet

Throws:

ModelException - if a DataSet with this ID already exists or if JSON was corrupt or missing required attributes

getDataSets

public Map<String,DataSet> getDataSets()

Returns a copy of ID-Network map. Once generated, membership of this map is not maintained.

Returns:

copy of ID-Network map

getDataSetList

public List<DataSet> getDataSetList()

Returns DataSets of this Model as a list

Returns:

list of DataSets

createLink

public Link createLink(Node source,
                       Node target,
                       CrossNetworkLink.Type type)
                throws LinkException

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

Parameters:

source - Node to link from

target - Node to link to

type - type of CrossNetworkLink; Type can not be CrossNetworkLink.Type.State, use createCrossNetworkLink(Node, Node, String) instead

Returns:

created Link

Throws:

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

createLink

public Link createLink(String sourceNetworkId,
                       String sourceNodeId,
                       String targetNetworkId,
                       String targetNodeId,
                       CrossNetworkLink.Type type)
                throws LinkException

Creates a CrossNetworkLink of given Type.

Parameters:

sourceNetworkId - ID of source Network of the link

sourceNodeId - ID of source Node of the link

targetNetworkId - ID of target Network of the link

targetNodeId - ID of target Node of the link

type - type of the message for the link to pass; Type can not be CrossNetworkLink.Type.State, use createCrossNetworkLink(Node, Node, String) instead

Returns:

created Link

Throws:

LinkException - if both Nodes are in the same Network; invalid Type given, or source Node already has incoming links or if Network with this ID does not exist

createLink

public Link createLink(Node source,
                       Node target,
                       State state)
                throws LinkException

Creates a CrossNetworkLink of type CrossNetworkLink.Type.State that passes the given state from source Node to target Node.

Parameters:

source - source Node of the link

target - target Node of the link

state - the state from source Node for the link to pass to target Node

Returns:

created Link

Throws:

LinkException - if both Nodes are in the same Network; invalid state given, or source Node already has incoming links

createLink

public Link createLink(String sourceNetworkId,
                       String sourceNodeId,
                       String targetNetworkId,
                       String targetNodeId,
                       String stateLabel)
                throws ModelException

Creates a CrossNetworkLink of type CrossNetworkLink.Type.State that passes the given state from source Node to target Node.

Parameters:

sourceNetworkId - ID of source Network of the link

sourceNodeId - ID of source Node of the link

targetNetworkId - ID of target Network of the link

targetNodeId - ID of target Node of the link

stateLabel - the label of the state from source Node for the link to pass to target Node

Returns:

created Link

Throws:

ModelException - if both Nodes are in the same Network; invalid state given, or source Node already has incoming links

NullPointerException - if Network with this ID does not exist

getJsonTexts

public org.json.JSONArray getJsonTexts()

Returns Risk Map texts stored as JSON

Returns:

Risk Map texts stored as JSON

getJsonPictures

public org.json.JSONArray getJsonPictures()

Returns Risk Map pictures stored as JSON

Returns:

Risk Map pictures stored as JSON

getJsonGraphics

public org.json.JSONObject getJsonGraphics()

Returns model graphics stored as JSON

Returns:

model graphics stored as JSON

getJsonAudit

public org.json.JSONObject getJsonAudit()

Returns audit stored as JSON

Returns:

audit stored as JSON

setLogicModel

protected void setLogicModel(uk.co.agena.minerva.model.Model logicModel)

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

Parameters:

logicModel - the logical model

getDataSet

public DataSet getDataSet(String id)

Looks up and returns a DataSet by its ID.

Parameters:

id - the ID of the DataSet to return

Returns:

the DataSet identified by ID or null, if no such DataSet exists in this Model

factorize

public boolean factorize()
                  throws ModelException

Performs binary factorization on the model if there are any simulation nodes with more than 3 parents.
This involves the model being recreated from scratch and all previously held references to pre-existing objects in the Model will become invalid and should be released.

Returns:

false if no factorization was required, true if successfully factorized

Throws:

ModelException - if failed to factorize

removeDataSet

public boolean removeDataSet(DataSet dataSet)

Removes the provided DataSet from the model

Parameters:

dataSet - DataSet to remove

Returns:

true if the DataSet was removed

convertToStatic

public void convertToStatic(DataSet dataSet)
                     throws NodeException,
                            AgenaRiskRuntimeException

Make all states of dynamically discretized nodes static as they currently are in the provided DataSet.
No action will be performed if no nodes are simulated.
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

Throws:

AgenaRiskRuntimeException - if failed to regenerate NPTs after conversion

NodeException - if failed for other reasons

reset

public void reset()

Reset the model by removing all Networks, Links, DataSets etc

getSettings

public Settings getSettings()

Returns Model Settings object.

Returns:

Model Settings object

isCalculated

public boolean isCalculated()

Checks whether the model had been successfully calculated and requires no calculation at this time.
Model is considered calculated if all Networks had been calculated.

Returns:

true if the model is in a calculated state and requires no further calculation

getAvailableDataSetId

public String getAvailableDataSetId(String prefix)

Generates a new DataSet ID that is guaranteed to be available at the return time.

Parameters:

prefix - String to prefix the generated ID

Returns:

new available DataSet ID