MCM

The MCM class represents a Minimally Complex Model (MCM). These are a family of maximum entropy models (known as spin models) that have interactions of arbitrarily high order grouped in a community-like structure, which are called independent complete components (ICCs).

An MCM object can be initialized explicitly using a binary matrix or gray code array, or using standard templates such as “independent”, “complete”, or “random”. This class supports flexible manipulation of the model structure through methods that add, remove, or move variables across components. It also provides methods for generating data from a system which has this model structure, either as a data file or a Data object.

An MCM object is also given as the output of a model selection procedure from the MCMSearch class. In such cases, additional methods are available to retrieve information about the optimal model for a given Data object.

class mcmpy.MCM

Initialization

__init__(n: int)

Constructs a new MCM object with a given number of variables.

The default partition is the independent model, where each variable is placed in its own component.

Parameters:: n (int) – Number of variables in the system.

__init__(n: int, partition: numpy.ndarray)

Constructs a new MCM object with a given number of variables and a specific partition.

The partition must be given as a 2D binary array or a 1D gray code array. See the attributes array and array_gray_code below for an example.

In the 2D representation each row represents an ICC and each column a variable. If a variable is present in a component, the corresponding element is one and zero otherwise.

In the 1D gray code representation, the elements correspond to the component index in which each variable is present. To indicate that a variable is not present in the model, the component index -1 is used.

Parameters:

n (int) – Number of variables in the system.
partition (numpy.ndarray) – Partition of the MCM

__init__(n: int, partition: str)

Constructs a new MCM object with a given number of variables and a partition type.

Valid partition types:

“independent” : All variables are placed in separate components.
“complete” : All variables are placed in a single component.
“random” : Each variable is assigned to a random component.

Parameters:

n (int) – Number of variables in the system.
partition (str) – String indicating the type of partition.

Methods

generate_data_file(N_samples: int, data: Data, filename: str)

Generates a file containing N samples from this MCM combined with a given dataset.

Parameters:

N_samples (int) – The number of samples that should be generated.
data (Data) – The dataset from which the model parameters are inferred.
filename (str) – Path to the file that will contain the generated data.

generate_data_object(N_samples: int, data: Data)

Generates a Data object containing N samples from this MCM combined with a given dataset.

Parameters:

N_samples (int) – The number of samples that should be generated.
data (Data) – The dataset from which the model parameters are inferred.

Returns:

A Data object containing the generated samples.

Return type:

Data

move_variable_in(var_index: int, comp_index: int)

Adds a variable to a specified component in the partition.

The variable index must be between 0 and \(n-1\) and refer to a variable that is not currently assigned to any component. The component index must also be between 0 and \(n-1\). If the specified component index exceeds the index of the first empty component, the variable will instead be added to the first available empty component. Note that this function will reset the optimized status of the MCM if it was the result of an MCMSearch before. The functions ‘print_info’, ‘get_best_log_evidence’ and ‘get_best_log_evidence_icc’ will no longer be available.

Parameters:

var_index (int) – Index of the variable to add.
comp_index (int) – Index of the component to where the variable will move.

move_variable_out(var_index: int)

Removes a specific variable from the partition.

The variable index must be between 0 and \(n-1\) and refer to a variable that is currently assigned to a component in the partition. After removal, the variable will no longer be associated with any component. Note that this function will reset the optimized status of the MCM if it was the result of an MCMSearch before. The functions ‘print_info’, ‘get_best_log_evidence’ and ‘get_best_log_evidence_icc’ will no longer be available.

Parameters:: var_index (int) – Index of the variable to remove.

move_variable(var_index: int, comp_index: int)

Moves a specific variable to another component.

The variable index should be a value between 0 and \(n-1\) and refer to a variable that is present in the partition. The given component index should be a value between 0 and \(n-1\). If the specified component index exceeds the index of the first empty component, the variable will instead be moved to the first available empty component. Note that this function will reset the optimized status of the MCM if it was the result of an MCMSearch before. The functions ‘print_info’, ‘get_best_log_evidence’ and ‘get_best_log_evidence_icc’ will no longer be available.

Parameters:

var_index (int) – Index of the variable to move.
comp_index (int) – Index of the component to where the variable will move.

Note

The following methods are only available when the MCM object is the result of an MCMSearch procedure.

print_details()

Prints out the information about the partition and the log-evidence of the MCM.

Every component of the MCM is printed out as a binary string combined with its log-evidence. Works only after a search for the best mcm has been run for a given dataset.

get_best_log_evidence()

Returns the best log-evidence of the MCM.

Works only after a search for the best mcm has been run for a given dataset.

Returns:: The log-evidence of the MCM.
Return type:: float

get_best_log_evidence_icc()

Returns the best log-evidence of the partition per component.

Works only after a search for the best mcm has been run for a given dataset.

Returns:: Array containing the log-evidence of every component of the MCM.
Return type:: numpy.ndarray

Attributes

n: int: The number of variables in the system (read-only).

n_icc: int: The number of independent complete components (ICCs) that the MCM has (read-only).

rank: int: The number of variables currently assigned to any component in the MCM (read-only).

array: numpy.ndarray

The partition of the MCM represented as a 2D binary array.

This attribute can be set using a 2D numpy array. Each row represents an ICC and each column corresponds to a variable. If a variable is present in a component, the corresponding element is one and zero otherwise. In the example below, the partition consists of 3 components. Component 1 contains only variable 0. Variables 1 and 3 make up the second component. The last component contains variable 2.

import numpy as np
from mcmpy import MCM

n = 4
partition = np.array([[1,0,0,0], [0,1,0,1], [0,0,1,0]])
model = MCM(n, partition)

array_gray_code: numpy.ndarray

The partition of the MCM represented as a 1D gray code array.

This attribute can be set using a 1D numpy array. The elements of the array correspond to the component index in which each variable is present. To indicate that a variable is not present in the model, the component index -1 is used. The same partition as in the example above in gray code form would be:

import numpy as np
from mcmpy import MCM

n = 4
partition = np.array([[0,1,2,1]])
model = MCM(n, partition)

is_optimized: boolean: Boolean value indicating whether the MCM is the result from an MCMSearch procedure (read-only).