API Reference

Node = Int16

Primitive type for node index. Alias for Int16.

Name = String

Primitive type for node names. Alias for String.

abstract type AbstractNode end

Node type for directed, acyclic graph.

struct ChanceNode <: AbstractNode

A struct for chance nodes, includes the name, information set, states and index of the node

struct DecisionNode <: AbstractNode

A struct for decision nodes, includes the name, information set, states and index of the node

struct ValueNode <: AbstractNode

A struct for value nodes, includes the name, information set and index of the node

const State = Int16

Primitive type for the number of states. Alias for Int16.

struct States <: AbstractArray{State, 1}

States type. Works like Vector{State}.

Examples

julia> S = States(State.([2, 3, 2, 4]))
4-element States:
 2
 3
 2
 4

const Path{N} = NTuple{N, State} where N

Path type. Alias for NTuple{N, State} where N.

const ForbiddenPath = Tuple{Vector{Node}, Set{Path}}

ForbiddenPath type.

Examples

julia> ForbiddenPath(([1, 2], Set([(1, 2)])))
(Int16[1, 2], Set(Tuple{Vararg{Int16,N}} where N[(1, 2)])

julia> ForbiddenPath[
    ([1, 2], Set([(1, 2)])),
    ([3, 4, 5], Set([(1, 2, 3), (3, 4, 5)]))
]
2-element Array{Tuple{Array{Int16,1},Set{Tuple{Vararg{Int16,N}} where N}},1}:
 ([1, 2], Set([(1, 2)]))
 ([3, 4, 5], Set([(1, 2, 3), (3, 4, 5)]))

const FixedPath = Dict{Node, State}

FixedPath type.

Examples

julia> FixedPath(Dict(1=>1, 2=>3))
Dict{Int16,Int16} with 2 entries:
  2 => 3
  1 => 1

function paths(states::AbstractVector{State})

Iterate over paths in lexicographical order.

Examples

julia> states = States(State.([2, 3]))
2-element States:
 2
 3

julia> vec(collect(paths(states)))
6-element Array{Tuple{Int16,Int16},1}:
 (1, 1)
 (2, 1)
 (1, 2)
 (2, 2)
 (1, 3)
 (2, 3)

function paths(states::AbstractVector{State}, fixed::FixedPath)

Iterate over paths with fixed states in lexicographical order.

Examples

julia> states = States(State.([2, 3]))
2-element States:
 2
 3

julia> vec(collect(paths(states, Dict(Node(1) => State(2)))))
3-element Array{Tuple{Int16,Int16},1}:
 (2, 1)
 (2, 2)
 (2, 3)

struct Probabilities{N} <: AbstractArray{Float64, N}

Construct and validate stage probabilities (probabilities for a single node).

Examples

julia> data = [0.5 0.5 ; 0.2 0.8]
2×2 Array{Float64,2}:
 0.5  0.5
 0.2  0.8

julia> X = Probabilities(Node(2), data)
2×2 Probabilities{2}:
 0.5  0.5
 0.2  0.8

julia> s = (1, 2)
(1, 2)

julia> X(s)
0.5

abstract type AbstractPathProbability end

Abstract path probability type.

struct DefaultPathProbability <: AbstractPathProbability

Path probability obtained as a product of the probability values corresponding to path s in each chance node.

Examples

julia> C = [2]
1-element Array{Int64,1}:
 2

julia> I_j = [[1]]
1-element Array{Array{Int64,1},1}:
 [1]

julia> X = [Probabilities(Node(2), [0.5 0.5; 0.2 0.8])]
1-element Array{Probabilities{2},1}:
 [0.5 0.5; 0.2 0.8]

julia> P = DefaultPathProbability(C, I_j, X)
DefaultPathProbability(Int16[2], Array{Int16,1}[[1]], Probabilities[[0.5 0.5; 0.2 0.8]])

julia> s = Path((1, 2))
(1, 2)

julia> P(s)
0.5

const Utility = Float32

Primitive type for utility. Alias for Float32.

struct Utilities{N} <: AbstractArray{Utility, N}

State utilities.

Examples

julia> vals = Utility.([1.0 -2.0; 3.0 4.0])
2×2 Array{Float32,2}:
 1.0  -2.0
 3.0   4.0

julia> Y = Utilities(Node(3), vals)
2×2 Utilities{2}:
 1.0  -2.0
 3.0   4.0

julia> s = Path((1, 2))
 (1, 2)

julia> Y(s)
-2.0f0

abstract type AbstractPathUtility end

Abstract path utility type.

struct DefaultPathUtility <: AbstractPathUtility

Default path utility obtained as a sum of the utility values corresponding to path s in each value node.

Examples

julia> vals = Utility.([1.0 -2.0; 3.0 4.0])
2×2 Array{Float32,2}:
 1.0  -2.0
 3.0   4.0

julia> Y = [Utilities(Node(3), vals)]
1-element Array{Utilities{2},1}:
 [1.0 -2.0; 3.0 4.0]

julia> I_3 = [[1,2]]
1-element Array{Array{Int64,1},1}:
 [1, 2]

julia> U = DefaultPathUtility(I_3, Y)
DefaultPathUtility(Array{Int16,1}[[1, 2]], Utilities[[1.0 -2.0; 3.0 4.0]])

julia> s = Path((1, 2))
(1, 2)

julia> U(s)
-2.0f0

julia> t = Utility(-100.0)


julia> U(s, t)
-102.0f0

mutable struct InfluenceDiagram
    Nodes::OrderedDict{Name, AbstractNode}
    Names::Vector{Name}
    I_j::OrderedDict{Name, Vector{Name}}
    States::OrderedDict{Name, Vector{Name}}
    S::OrderedDict{Name,State}

    C::OrderedDict{Name, ChanceNode}
    D::OrderedDict{Name, DecisionNode}
    V::OrderedDict{Name, ValueNode}
    X::OrderedDict{Name, Probabilities}
    Y::OrderedDict{Name, Utilities}
    P::AbstractPathProbability
    U::AbstractPathUtility
    translation::Utility
    function InfluenceDiagram()
        new(OrderedDict{String, AbstractNode}())
    end
end

Hold all information related to the influence diagram.

Fields

All OrderedDicts are ordered by vector Names.

• Nodes::OrderedDict{Name, AbstractNode}: OrderedDict of node names as key

and their respective abstract nodes as values.

• Names::Vector{Name}: Names of nodes in order of their indices.
• I_j::OrderedDict{Name, Vector{Name}}: Information sets of nodes by their name.
• States::OrderedDict{Name, Vector{Name}}: States of each node by their name.
• S::OrderedDict{Name,State}: Number of states of each node.
• C::OrderedDict{Name, ChanceNode}: Chance nodes by their name.
• D::OrderedDict{Name, DecisionNode}: Decision nodes by their name.
• V::OrderedDict{Name, ValueNode}: Values nodes by their name.
• X::OrderedDict{Name, Probabilities}: Probability matrices of chance nodes by their name.
• Y::OrderedDict{Name, Utilities}: Utility matrices of value nodes by their name.
• P::AbstractPathProbability: Path probabilities.
• U::AbstractPathUtility: Path utilities.
• translation::Utility: Utility translation for storing the positive or negative utility translation.
• RJT::RJT: Rooted junction tree associated with the diagram.

Examples

diagram = InfluenceDiagram()

function add_node!(diagram::InfluenceDiagram, node::AbstractNode)

Add node to influence diagram structure.

Examples

julia> add_node!(diagram, ChanceNode("O", [], ["lemon", "peach"]))
1-element Array{AbstractNode,1}:
 ChanceNode("O", String[], ["lemon", "peach"])

struct ProbabilityMatrix{N} <: AbstractArray{Float64, N}
    nodes::Vector{Name}
    indices::Vector{Dict{Name, Int}}
    matrix::Array{Float64, N}
end

Construct probability matrix.

function ProbabilityMatrix(diagram::InfluenceDiagram, node::Name)

Initialise a probability matrix for a given chance node. The matrix is initialised with zeros.

Examples

julia> X_O = ProbabilityMatrix(diagram, "O")
2-element ProbabilityMatrix{1}:
 0.0
 0.0

function add_probabilities!(diagram::InfluenceDiagram, node::Name, probabilities::AbstractArray{Float64, N}) where N

Add probability matrix to influence diagram, specifically to its X vector.

Examples

julia> X_O = ProbabilityMatrix(diagram, "O")
2-element ProbabilityMatrix{1}:
 0.0
 0.0

julia> X_O["lemon"] = 0.2
0.2

julia> add_probabilities!(diagram, "O", X_O)
ERROR: DomainError with Probabilities should sum to one.:

julia> X_O["peach"] = 0.8
0.2

julia> add_probabilities!(diagram, "O", X_O)
1-element Array{Probabilities,1}:
 [0.2, 0.8]

struct UtilityMatrix{N} <: AbstractArray{Utility, N}
    I_v::Vector{Name}
    indices::Vector{Dict{Name, Int}}
    matrix::Array{Utility, N}
end

Construct utility matrix.

function UtilityMatrix(diagram::InfluenceDiagram, node::Name)

Initialise a utility matrix for a value node. The matrix is initialised with Inf values.

Examples

julia> Y_V3 = UtilityMatrix(diagram, "V3")
2×3 UtilityMatrix{2}:
 Inf  Inf  Inf
 Inf  Inf  Inf

function add_utilities!(diagram::InfluenceDiagram, node::Name, utilities::AbstractArray{T, N}) where {N,T<:Real}

Add utility matrix to influence diagram, specifically to its Y vector.

Examples

julia> Y_V3 = UtilityMatrix(diagram, "V3")
2×3 UtilityMatrix{2}:
 Inf  Inf  Inf
 Inf  Inf  Inf

julia> Y_V3["peach", :] = [-40, -20, 0]
3-element Array{Int64,1}:
 -40
 -20
   0

julia> Y_V3["lemon", :] = [-200, 0, 0]
3-element Array{Int64,1}:
 -200
    0
    0

julia> add_utilities!(diagram, "V3", Y_V3)
1-element Array{Utilities,1}:
 [-200.0 0.0 0.0; -40.0 -20.0 0.0]

julia> add_utilities!(diagram, "V1", [0, -25])
2-element Array{Utilities,1}:
 [-200.0 0.0 0.0; -40.0 -20.0 0.0]
 [0.0, -25.0]

function generate_arcs!(diagram::InfluenceDiagram)

Generate arc structures using nodes added to influence diagram and storing them to variable diagram.I_j. Also creating variables diagram.States, diagram.S, diagram.C, diagram.D and diagram.V and storing appropriate values to them.

Examples

generate_arcs!(diagram)

function generate_diagram!(diagram::InfluenceDiagram;
default_probability::Bool=true,
default_utility::Bool=true,
positive_path_utility::Bool=false,
negative_path_utility::Bool=false)

Generate complete influence diagram with probabilities and utilities included.

Arguments

• default_probability::Bool=true: Choice to use default path probabilities.
• default_utility::Bool=true: Choice to use default path utilities.
• positive_path_utility::Bool=false: Choice to use a positive path utility translation.
• negative_path_utility::Bool=false: Choice to use a negative path utility translation.

Examples

generate_diagram!(diagram)

struct RJT

A struct for rooted junction trees.

Fields

• clusters::Dict{Name, Vector{Name}}: Dictionary of clusters in an RJT with the root node as key and the names of nodes in a cluster as values.
• arcs::Vector{Tuple{Name, Name}}: Arcs between clusters specified as a vector tuples with root node names defining the clusters.

function indices(dict)

Get the indices of nodes in values of a Dict or OrderedDict.

Example

julia> D_indices = indices(diagram.D)
3-element Vector{Int16}:
 3
 6
 9

function I_j_indices(diagram::InfluenceDiagram, dict)

Get the indices of information sets of nodes in values of a Dict or OrderedDict. Returns Vector{Vector{Node}}.

Example

julia> C_I_j_indices = I_j_indices(diagram, diagram.C)
7-element Vector{Vector{Int16}}:
 []
 [1]
 [1, 3]
 [4]
 [4, 6]
 [7]
 [7, 9]

function indices_in_vector(diagram::InfluenceDiagram, nodes::AbstractArray)

Get the indices of an array of nodes and store them in an array.

Example

julia> idcs_T1_H2 = indices_of(diagram, ["T1", "H2"])
2-element Vector{Int16}:
 2
 4

function get_values(dict::OrderedDict)

Generic function to get values from an OrderedDict.

Example

julia> D_nodes = get_values(diagram.D)
3-element Vector{DecisionNode}:
 DecisionNode("D1", ["T1"], ["treat", "pass"], 3)
 DecisionNode("D2", ["T2"], ["treat", "pass"], 6)
 DecisionNode("D3", ["T3"], ["treat", "pass"], 9)

function get_keys(dict::OrderedDict)

Generic function to get keys from an OrderedDict.

Example

julia> D_values = get_keys(diagram.D)
3-element Vector{String}:
 "D1"
 "D2"
 "D3"

function num_states(diagram::InfluenceDiagram, name::Name)

Get the number of states in a given node.

Example

julia> NS_O = num_states(diagram, "O")
2

function ForbiddenPath(diagram::InfluenceDiagram, nodes::Vector{Name}, paths::Vector{NTuple{N, Name}}) where N

ForbiddenPath outer construction function. Create ForbiddenPath variable.

Arguments

• diagram::InfluenceDiagram: Influence diagram structure
• nodes::Vector{Name}: Vector of nodes involved in forbidden paths. Identified by their names.
• paths::Vector{NTuple{N, Name}}`: Vector of tuples defining the forbidden combinations of states. States identified by their names.

Example

ForbiddenPath(diagram, ["R1", "R2"], [("high", "low"), ("low", "high")])

function FixedPath(diagram::InfluenceDiagram, fixed::Dict{Name, Name})

FixedPath outer construction function. Create FixedPath variable.

Arguments

• diagram::InfluenceDiagram: Influence diagram structure
• fixed::Dict{Name, Name}: Dictionary of nodes and their fixed states. Order is node=>state, and both are idefied with their names.

Example

julia> fixedpath = FixedPath(diagram, Dict("O" => "lemon"))
Dict{Int16,Int16} with 1 entry:
  1 => 1

julia> vec(collect(paths(states, fixedpath)))
3-element Array{Tuple{Int16,Int16},1}:
 (1, 1)
 (1, 2)
 (1, 3)

LocalDecisionStrategy{N} <: AbstractArray{Int, N}

Local decision strategy type.

function LocalDecisionStrategy(rng::AbstractRNG, diagram::InfluenceDiagram, d::Node)

Generate random decision strategy for decision node d.

Examples

rng = MersenneTwister(3)
diagram = InfluenceDiagram()
random_diagram!(rng, diagram, 5, 2, 3, 2, 2, rand(rng, [2,3], 5))
LocalDecisionStrategy(rng, diagram, diagram.D[1])

DecisionStrategy

Decision strategy type.

DecisionVariables(model::Model,  diagram::InfluenceDiagram; names::Bool=true)

Create decision variables and constraints.

Arguments

• model::Model: JuMP model into which variables are added.
• diagram::InfluenceDiagram: Influence diagram structure.
• names::Bool: Use names or have JuMP variables be anonymous.

Examples

z = DecisionVariables(model, diagram)

PathCompatibilityVariables(model::Model,
    diagram::InfluenceDiagram,
    z::OrderedDict{Name, DecisionVariable};
    names::Bool=false,
    name::String="x",
    forbidden_paths::Vector{ForbiddenPath}=ForbiddenPath[],
    fixed::FixedPath=Dict{Node, State}(),
    probability_cut::Bool=true,
    probability_scale_factor::Float64=1.0)

Create path compatibility variables and constraints.

Arguments

• model::Model: JuMP model into which variables are added.
• diagram::InfluenceDiagram: Influence diagram structure.
• z::OrderedDict{Name, DecisionVariable}: Ordered dictionary of decision variables.
• names::Bool: Use names or have JuMP variables be anonymous.
• name::String: Prefix for predefined decision variable naming convention.
• forbidden_paths::Vector{ForbiddenPath}: The forbidden subpath structures. Path compatibility variables will not be generated for paths that include forbidden subpaths.
• fixed::FixedPath: Path compatibility variable will not be generated for paths which do not include these fixed subpaths.
• probability_cut Includes probability cut constraint in the optimisation model.
• probability_scale_factor::Float64: Adjusts conditional value at risk model to be compatible with the expected value expression if the probabilities were scaled there.

Examples

x_s = PathCompatibilityVariables(model, diagram, z; probability_cut = false)

lazy_probability_cut(model::Model, diagram::InfluenceDiagram, x_s::PathCompatibilityVariables)

Add a probability cut to the model as a lazy constraint.

Examples

lazy_probability_cut(model, diagram, x_s)

expected_value(model::Model,
    diagram::InfluenceDiagram,
    x_s::PathCompatibilityVariables)

Create an expected value objective.

Arguments

• model::Model: JuMP model into which variables are added.
• diagram::InfluenceDiagram: Influence diagram structure.
• x_s::PathCompatibilityVariables: Path compatibility variables.

Examples

EV = expected_value(model, diagram, x_s)

conditional_value_at_risk(model::Model,
    diagram::InfluenceDiagram,
    x_s::PathCompatibilityVariables{N},
    α::Float64;
    probability_scale_factor::Float64=1.0) where N

Create a conditional value-at-risk (CVaR) objective.

Arguments

• model::Model: JuMP model into which variables are added.
• diagram::InfluenceDiagram: Influence diagram structure.
• x_s::PathCompatibilityVariables: Path compatibility variables.
• α::Float64: Probability level at which conditional value-at-risk is optimised.
• probability_scale_factor::Float64: Adjusts conditional value at risk model to be compatible with the expected value expression if the probabilities were scaled there.

Examples

α = 0.05  # Parameter such that 0 ≤ α ≤ 1
CVaR = conditional_value_at_risk(model, x_s, U, P, α)
CVaR = conditional_value_at_risk(model, x_s, U, P, α; probability_scale_factor = 10.0)

LocalDecisionStrategy(d::Node, z::Array{VariableRef})

Construct decision strategy from variable refs.

DecisionStrategy(diagram::InfluenceDiagram, z::OrderedDict{Name, DecisionVariable})

Extract values for decision variables from solved decision model.

Examples

Z = DecisionStrategy(diagram, z)

RJTVariables(model, diagram, z)

Using the influence diagram and decision variables z from DecisionProgramming.jl, adds the variables and constraints of the corresponding RJT model.

Arguments

• model::Model: JuMP model into which variables are added.
• diagram::InfluenceDiagram: Influence diagram structure.
• z::OrderedDict{Name, DecisionVariable}: Decision variables from DecisionVariables function.

Examples

μ_s = RJTVariables(model, diagram, z)

expected_value(model::Model, diagram::InfluenceDiagram, μVars::RJTVariables)

Construct the RJT objective function.

Arguments

• model::Model: JuMP model into which variables are added.
• diagram::InfluenceDiagram: Influence diagram structure.
• μVars::RJTVariables: Vector of moments.

Examples

EV = expected_value(model, diagram, μ_s)

conditional_value_at_risk(model::Model,
    diagram::InfluenceDiagram,
    μVars::RJTVariables,
    α::Float64)

Create a conditional value-at-risk (CVaR) objective based on RJT model.

The model can't have more than one value node.

Arguments

• model::Model: JuMP model into which variables are added.
• diagram::InfluenceDiagram: Influence diagram structure.
• μVars::RJTVariables: Vector of moments.
• α::Float64: Probability level at which conditional value-at-risk is optimised.

Examples

α = 0.05  # Parameter such that 0 ≤ α ≤ 1
CVaR = conditional_value_at_risk(model, diagram, μ_s, α)

generate_model(diagram::InfluenceDiagram; names::Bool=true, model_type::String, probability_cut::Bool=false)

Generate either decision programming based or RJT based variables and the respective objective function

Examples

julia> generate_model(diagram, model_type="RJT")

randomStrategy(diagram::InfluenceDiagram)

Generates a random decision strategy for the problem. Returns the strategy as well as the expected utility of the strategy and the paths that are compatible with the strategy.

Arguments

• diagram::InfluenceDiagram: Influence diagram structure.

Examples

objval, Z, S_active = randomStrategy(diagram)

singlePolicyUpdate(diagram::InfluenceDiagram, model::Model, z::OrderedDict{Name, DecisionVariable}, x_s::PathCompatibilityVariables)

Finds a feasible solution using single policy update and sets the model start values to that solution. Returns a vector of tuples consisting of the value of each improved solution starting from a random policy, time (in milliseconds) since the function call and the decision strategy that gave the improved value. The purpose of all this output is to allow us to examine how fast the method finds good solutions.

Arguments

• diagram::InfluenceDiagram: Influence diagram structure.
• model::Model: The decision model, modelled in JuMP
• z::OrderedDict{Name, DecisionVariable}: The decision variables
• x_s::Union{PathCompatibilityVariables, Nothing}: The path compatibility variables if used.

Examples

solutionhistory = singlePolicyUpdate(diagram, model, z, x_s)

struct CompatiblePaths
    S::States
    C::Vector{Node}
    Z::DecisionStrategy
    fixed::FixedPath
end

CompatiblePaths type.

CompatiblePaths(diagram::InfluenceDiagram, Z::DecisionStrategy, fixed::FixedPath=Dict{Node, State}())

CompatiblePaths outer construction function. Interface for iterating over paths that are compatible and active given influence diagram and decision strategy.

1. Initialize path s of length n
2. Fill chance states s[C] by generating subpaths paths(C)
3. Fill decision states s[D] by decision strategy Z and path s

Examples

for s in CompatiblePaths(diagram, Z)
    ...
end

struct UtilityDistribution
    u::Vector{Float64}
    p::Vector{Float64}
end

UtilityDistribution type.

UtilityDistribution(diagram::InfluenceDiagram, Z::DecisionStrategy)

Construct the probability mass function for path utilities on paths that are compatible with given decision strategy.

Examples

UtilityDistribution(diagram, Z)

struct StateProbabilities
    probs::Dict{Node, Vector{Float64}}
    fixed::FixedPath
end

StateProbabilities type.

StateProbabilities(diagram::InfluenceDiagram, Z::DecisionStrategy)

Associate each node with array of probabilities for each of its states occuring in compatible paths.

Examples

StateProbabilities(diagram, Z)

StateProbabilities(diagram::InfluenceDiagram, Z::DecisionStrategy, node::Name, state::Name, prior_probabilities::StateProbabilities)

Associate each node with array of conditional probabilities for each of its states occuring in compatible paths given fixed states and prior probability. Fix node and state using their names.

Examples

# Prior probabilities
prior_probabilities = StateProbabilities(diagram, Z)

# Select node and fix its state
node = "R"
state = "no test"
StateProbabilities(diagram, Z, node, state, prior_probabilities)

value_at_risk(U_distribution::UtilityDistribution, α::Float64)

Calculate value-at-risk.

conditional_value_at_risk(U_distribution::UtilityDistribution, α::Float64)

Calculate conditional value-at-risk.

print_decision_strategy(diagram::InfluenceDiagram, Z::DecisionStrategy, state_probabilities::StateProbabilities; show_incompatible_states::Bool = false)

Print decision strategy.

Arguments

• diagram::InfluenceDiagram: Influence diagram structure.
• Z::DecisionStrategy: Decision strategy structure with optimal decision strategy.
• state_probabilities::StateProbabilities: State probabilities structure corresponding to optimal decision strategy.
• show_incompatible_states::Bool: Choice to print rows also for incompatible states.

Examples

print_decision_strategy(diagram, Z, S_probabilities)

print_utility_distribution(U_distribution::UtilityDistribution; util_fmt="%f", prob_fmt="%f")

Print utility distribution.

Examples

U_distribution = UtilityDistribution(diagram, Z)
print_utility_distribution(U_distribution)

print_state_probabilities(diagram::InfluenceDiagram, state_probabilities::StateProbabilities, nodes::Vector{Name}; prob_fmt="%f")

Print state probabilities with fixed states.

Examples

S_probabilities = StateProbabilities(diagram, Z)
print_state_probabilities(S_probabilities, ["R"])
print_state_probabilities(S_probabilities, ["A"])

print_statistics(U_distribution::UtilityDistribution; fmt = "%f")

Print statistics about utility distribution.

print_risk_measures(U_distribution::UtilityDistribution, αs::Vector{Float64}; fmt = "%f")

Print risk measures.

print_node(node_name::String, diagram::InfluenceDiagram; print_tables::Bool=true)

Print node information. print_tables determines whether probability and utility tables for the node are printed.

Examples

print_node("H2", diagram)

print_diagram(diagram::InfluenceDiagram; print_tables::Bool=true)

Print diagram. print_tables determines whether probability and utility values for the nodes in the diagram are printed.

Examples

print_diagram(diagram)

mermaid(diagram::InfluenceDiagram, filename::String="mermaid_graph.png")

Print mermaid graph.