API reference

add_concept!(fcm, label; text = String(concept)) -> fcm

Adds a new concept to a fuzzy cognitive map.

add_link!(fcm, from, to, weight) -> fcm

Adds a link between concepts from and to in the fuzzy cognitive map fcm. The weight of the link is given by weight, which is usually a value in the range [-1, 1] or (0, 1]. Zero is not an accepted value, as that would be equivalent to a nonexistent link.

concept_labels(fcm)::Vector

Returns a list of the labels of all concepts in fcm.

This is just an eager version of MetaGraphsNext.labels.

concept_texts(fcm)::Vector

Returns a list of the textual descriptions of all concepts in fcm.

concepts(fcm)::Vector

Returns a list of label–text pairs for all concepts in fcm.

links(fcm)::Vector

Returns a list of all the links in fcm.

new_fcm(; concept_type = Symbol, name_type = String, weight_type = Float64)::MetaGraph

Creates an empty fuzzy cognitive map.

This returns a MetaGraphsNext.MetaGraph where the label type is concept_type, the vertex data type is name_type, and the edge data and weight types are both weight_type.

The returned object should be used to construct the conceptual mapping in terms of concepts and the links between them. For inference, where each concept gets associated with a real value, we use the FCMInferenceState type instead.

set_weight!(fcm, from, to, weight) -> fcm

Modifies the weight of an existing link between from and to. Using a zero value for weight deletes the link. (This is equivalent to calling delete!(fcm, from, to).)

FCMInferenceState

Represents the association of a numerical value with each concept in a fuzzy cognitive map, enabling inference based on it.

Constructor

FCMInferenceState(fcm, [activation]; kwargs...)

Constructs an FCMInferenceState based on the conceptual map stored in fcm.

activation specifies the initial concept values in one of the following ways:

• As a single item. In this case, the same value is used for all concepts.
• As a vector. This allows one to specify a particular value for each concept. The length of the vector must be equal to the number of concepts, and the elements must be in the same order as the concepts they correspond to in labels(fcm).
• As a dictionary. This allows one to specify a particular value for selected concepts. The dictionary must map concept labels to values. A missing key can be used to provide a default value for concepts that are not listed explicitly.

If no values are given, or in the case of a dictionary, no missing key is present, the default activation value is zero.

The available keyword parameters and their default values are as follows:

• copy_fcm = true: Whether to store a copy of fcm inside the FCMInferenceState, as opposed to a reference to the original object. If this is false, care must be taken when modifying the original object, as such changes will not be reflected in the inference state object and may easily invalidate it.
• threshold = clamp_threshold(:onesided): The threshold function to use during inference.
• state_gain = 0: How much the next value of a concept depends on the current value. Commonly set to 1 for driver concepts. May not be used together with drivers.
• drivers = missing: An iterable sequence of labels for concepts that are drivers. This is equivalent to setting state_gain to 1 for these concepts and zero for all others, and the parameter may not be used together with state_gain.
• input_gain = 1: How much the next value of a concept depends on the values of concepts that are linked to it.

threshold, state_gain, and input_gain can be specified on a per-concept basis in the same manner as the activation parameter. For an explanation of how these parameters factor into the inference process, see iterate_fcm.

The following common threshold function generators are provided by the library for convenient use with the threshold parameter.

• clamp_threshold
• sigmoid_threshold
• step_threshold

(Note that these are functions that return threshold functions; they are not threshold functions themselves.) It is also possible to pass a custom threshold function.

clamp_threshold(sidedness = :twosided) -> Function

Returns the clamping function

\[f(x) = \begin{cases} 0 & x < 0 \\ 1 & x > 1 \\ x & \text{otherwise} \end{cases}\]

if sidedness == :onesided and

\[f(x) = \begin{cases} -1 & x < -1 \\ 1 & x > 1 \\ x & \text{otherwise} \end{cases}\]

if sidedness == :twosided.

concept_values(state::FCMInferenceState)

Returns (a view of) the concept values in state.

conceptual_map(state::FCMInferenceState)

Returns the FCM associated with state.

Note that modifications to the returned FCM will generally invalidate state and should therefore be avoided.

infer(state::FCMInferenceState; kwargs...) -> (state, output, converged)

Performs inference with automatic convergence detection and returns the resulting state, the activation values at each inference step, and a boolean that indicates whether the inference converged.

The inference is performed by successive applications of iterate_fcm, and we refer to its documentation for information about how this works.

The halting criterion depends on these keyword parameters:

• max_iterations: The maximum number of iterations, by default 100.
• atol, rtol: The absolute and relative tolerances.

Convergence is assumed to have been attained once isapprox(previous, current; atol, rtol) is true for all activation values.

iterate_fcm(state::FCMInferenceState) -> new_state
iterate_fcm(state::FCMInferenceState, steps::Integer) -> (new_state, outputs)

Performs one or more iterations of the inference process.

The first version of this function performs a single iteration and returns the new state. The second version calls the first one steps number of times, storing the activation values at each step. It returns both the resulting state and an $M \times N$ matrix of activation values, where $M$ is the number of concepts and $N$ is the number of steps.

At each step, the next value of a concept is computed as

\[a_i[k+1] = f_i \left(\sigma_i a_i[k] + \gamma_i \sum_{j = 1}^M w_{ji} a_j[k]\right).\]

Here, $a_i[k]$ denotes the activation value of concept $i$ at step $k$; $w_{ji}$ is the weight of the link from concept $j$ to concept $i$; and $f_i$, $\sigma_i$, and $\gamma_i$ are, respectively, the threshold function, state gain, and input gain for concept $i$.

$\sigma_i$ is commonly set to 1 for driver concepts. Such concepts get their values from outside the FCM and have no incoming links, and without a state gain, their values will become zero on the first iteration.

Note that a nonzero $\sigma_i$ has the same effect as a nonzero diagonal element $w_{ii}$, i.e., a self-link from concept $i$ to itself. Self-links with weight 1 is a common way to construct driver concepts. The advantage of using a state gain is that it does not affect the graph structure of the FCM and therefore has no impact on structural analyses (e.g. centrality, paths, etc.).

sigmoid_threshold(sidedness = :twosided; steepness = 1.0) -> Function

Returns the sigmoid function

\[f(x) = \frac{\tanh(a (2x - 1)) + 1}{2}\]

if sidedness == :onesided and

\[f(x) = \tanh(a x)\]

if sidedness == :twosided, where $a$ is steepness.

step_threshold(sidedness = :twosided; mid_value = 1.0) -> Function

Returns the step function

\[f(x) = \begin{cases} 0 & x < \frac{1}{2} \\ m & x = \frac{1}{2} \\ 1 & x > \frac{1}{2} \end{cases}\]

if sidedness == :onesided and

\[f(x) = \begin{cases} 0 & x < 0 \\ m & x = 0 \\ 1 & x > 0 \end{cases}\]

if sidedness == :twosided, where $m$ is mid_value.

export_dot(io::IO, fcm)
export_dot(filename::AbstractString, fcm)

Exports a fuzzy cognitive map to the Graphviz DOT format.

import_csv(filename::AbstractString; kwargs...)
import_csv(io::IO; kwargs...)
import_csv(csv::CSV.File; kwargs...)

Imports an FCM from a CSV file. This is only supported if the CSV package has been loaded.

The CSV file to import can be specified using its path, an already-opened IO object, or a CSV.File object. Use the latter when full control of the CSV parsing is needed, e.g. for custom delimiters or other non-standard formatting.

A CSV file representing an FCM with N concepts must be structured as follows:

• In row 1, columns 2 to N+1 must contain the concept names
• In column 1, rows 2 to N+2 must contain the same concept names in the same order
• The cell in row 1, column 1 is ignored.
• The cell in row i, column j, where i and j are both greater than 1, must contain the weight of the link from concept i to concept j.
• An empty or zero cell is interpreted as “no link”.

The following keyword parameters may be used:

• max_concepts: The maximum number of concepts to load from the CSV file. This is useful if the CSV file has extra rows or columns that should not be included. The default is to read the entire file.