Boolean Function

Created on Tue Aug 12 11:03:49 2025

@author: Benjamin Coberly, Claus Kadelka

boolforge.boolean_function.display_truth_table(*functions: BooleanFunction, labels=None)[source]

Display the full truth table of a BooleanFunction in a formatted way.

Each row shows the input combination (x1, x2, …, xn) and the corresponding output(s) f(x).

Parameters:

*functions (BooleanFunction): One or more BooleanFunction objects.

labels (list[str], optional): Column labels for each function (defaults to f1, f2, …).

Example:

>>> f = BooleanFunction("(x1 & ~x2) | x3")
>>> display_truth_table(f)

boolforge.boolean_function.get_layer_structure_from_canalized_outputs(can_outputs: list) → list[source]

Composes the layer structure when given canalized outputs.

Parameters:

can_outputs (list[int] | np.array[int]): Array of canalized output values.

Returns:

list[int]: The composed layer structure for the provided canalized outputs.

class boolforge.boolean_function.BooleanFunction(f: list | array | str, name: str = '')[source]

Bases: object

A class representing a Boolean function.

Constructor Parameters:

f (list[int] | np.array[int] | str): A list of length 2^n representing the outputs of a Boolean function with n inputs, or a string that can be properly evaluated, see utils.f_from_expression.

name (str, optional): The name of the node regulated by the Boolean function (default ‘’).

Members:

f (np.array[int]): A numpy array of length 2^n representing the outputs of a Boolean function with n inputs.

n (int): The number of inputs for the Boolean function.

variables (np.array[str]): A numpy array of n strings with variable names, default x0, …, x_{n-1}.

name (str): The name of the node regulated by the Boolean function (default ‘’).

properties (dict[str:Variant]): Dynamically created dictionary with additional information about the function (canalizing layer structure, type of inputs, etc.).

classmethod from_cana(cana_BooleanNode: cana.boolean_node.BooleanNode) → BooleanFunction[source]

Compatability Method:

Converts an instance of cana.boolean_node.BooleanNode from the cana module into a Boolforge BooleanFunction object.

Returns:

A BooleanFunction object.

__str__()[source]: Return str(self).

__repr__()[source]: Return repr(self).

__add__(value)[source]

Element-wise Boolean addition: +.

Supports:

BooleanFunction * BooleanFunction

BooleanFunction * int (0 or 1)

Returns:

BooleanFunction: The result of element-wise addition modulo 2.

__mul__(value)[source]

Element-wise Boolean multiplication (logical AND): *.

Supports:

BooleanFunction * BooleanFunction

BooleanFunction * int (0 or 1)

Returns:

BooleanFunction: The result of element-wise multiplication.

__rmul__(value)[source]

Element-wise Boolean multiplication (logical AND): *.

Supports:

BooleanFunction * BooleanFunction

int (0 or 1) * BooleanFunction

Returns:

BooleanFunction: The result of element-wise multiplication.

__and__(value)[source]

Element-wise logical AND: &.

Supports:

BooleanFunction & BooleanFunction

BooleanFunction & int (0 or 1)

Returns:

BooleanFunction: The result of the logical AND.

__or__(value)[source]

Element-wise logical OR: |.

Supports:

BooleanFunction | BooleanFunction

BooleanFunction | int (0 or 1)

Returns:

BooleanFunction: The result of the logical OR.

__xor__(value)[source]

Element-wise logical XOR: ^.

Supports:

BooleanFunction ^ BooleanFunction
BooleanFunction ^ int (0 or 1)

Returns:

BooleanFunction: The result of the logical XOR.

__invert__()[source]

Element-wise negation: ~.

Returns:

BooleanFunction: The result of element-wise negation.

__call__(values)[source]: Call self as a function.

to_polynomial() → str[source]

Returns the Boolean function converted into polynomial format in non-reduced DNF.

Returns:

str: Polynomial format in non-reduced DNF of the Boolean function.

to_truth_table(RETURN: bool = True, filename: str = None) → DataFrame[source]

Returns or saves the full truth table of the Boolean function as a pandas DataFrame.

Each row shows the input combination (x1, x2, …, xn) and the corresponding output f(x).

Parameters:

RETURN (bool, optional): Whether to return the DataFrame (default: True). If False, the function only writes the table to file when filename is provided.

filename (str, optional): File name (including extension) to which the truth table should be saved. Supported formats are ‘csv’, ‘xls’, and ‘xlsx’. If provided, the truth table is automatically saved in the specified format.

Returns:

pd.DataFrame: The full truth table, if RETURN=True. Otherwise, nothing is returned.

Example

>>> f = BooleanFunction("(x1 & ~x2) | x3")
>>> f.to_truth_table()
    x1  x2  x3  f
  0   0   0  0
  0   0   1  1
  0   1   0  0
  0   1   1  1
  1   0   0  1
  1   0   1  1
  1   1   0  0
  1   1   1  1

Notes:

The column names correspond to the function’s variables followed by its name.

When saving to a file, the file extension determines the format.

to_cana() → cana.boolean_node.BooleanNode[source]

Compatability method:

Returns an instance of cana.boolean_node.BooleanNode from the cana module.

Returns:

An instance of cana.boolean_node.BooleanNode.

to_logical(AND: str = '&', OR: str = '|', NOT: str = '!', MINIMIZE_EXPRESSION: bool = True) → str[source]

Transform a Boolean function from truth table format to logical expression format.

Parameters:

AND (str, optional): Character(s) to use for the And operator. Defaults to ‘&’.

OR (str, optional): Character(s) to use for the Or operator. Defaults to ‘|’.

NOT (str, optional): Character(s) to use for the Not operator. Defaults to ‘!’.

MINIMIZE_EXPRESSION (bool, optional): Whether or not to minimize the expression using Espresso. If true, minimizes the expression. If false, keeps the expression in DNF form. Defaults to true.

Returns:

str: A string representing the Boolean function.

is_constant() → bool[source]

Check whether a Boolean function is constant.

Returns:

bool: True if f is constant (all outputs are 0 or all are 1), False otherwise.

is_degenerate() → bool[source]: Determine if a Boolean function contains non-essential variables. Numba-accelerated version.

is_monotonic() → bool[source]

Determine if a Boolean function is monotonic.

A Boolean function is monotonic if it is monotonic in each variable. That is, if for all i=1,…,n: f(x_1, …, x_i=0, …, x_n) >= f(x_1, …, x_i=1, …, x_n) for all (x_1, …, x_n) or f(x_1, …, x_i=0, …, x_n) <= f(x_1, …, x_i=1, …, x_n) for all (x_1, …, x_n).

Returns:

bool: True if f contains no conditional variables, False if at least one variable is conditional.

is_canalizing() → bool[source]

Determine if a Boolean function is canalizing.

A Boolean function f(x_1, …, x_n) is canalizing if there exists at least one variable x_i and a value a ∈ {0, 1} such that f(x_1, …, x_i = a, …, x_n) is constant.

Returns:

bool: True if f is canalizing, False otherwise.

is_k_canalizing(k: int) → bool[source]

Determine if a Boolean function is k-canalizing.

A Boolean function is k-canalizing if it has at least k conditionally canalizing variables. This is checked recursively: after fixing a canalizing variable (with a fixed canalizing input that forces the output), the subfunction must itself be canalizing for the next variable, and so on.

Parameters:

k (int): The desired canalizing depth (0 ≤ k ≤ n). Note: every function is 0-canalizing.

Returns:

bool: True if f is k-canalizing, False otherwise.

References:

He, Q., & Macauley, M. (2016). Stratification and enumeration of Boolean functions by canalizing depth. Physica D: Nonlinear Phenomena, 314, 1-8.

Dimitrova, E., Stigler, B., Kadelka, C., & Murrugarra, D. (2022). Revealing the canalizing structure of Boolean functions: Algorithms and applications. Automatica, 146, 110630.

is_kset_canalizing(k: int) → bool[source]

Determine if a Boolean function is k-set canalizing.

A Boolean function is k-set canalizing if there exists a set of k variables such that setting these variables to specific values forces the output of the function, irrespective of the other n - k inputs.

Parameters:

k (int): The size of the variable set (with 0 ≤ k ≤ n).

Returns:

bool: True if f is k-set canalizing, False otherwise.

References:

Kadelka, C., Keilty, B., & Laubenbacher, R. (2023). Collectively canalizing Boolean functions. Advances in Applied Mathematics, 145, 102475.

get_hamming_weight() → int[source]

Calculate the number of non-zero bits in the bit vector representing a Boolean function.

Returns:

int: The number of non-zero bits in the bit vector.

get_essential_variables() → list[source]

Determine the indices of essential variables in a Boolean function.

A variable is essential if changing its value (while holding the others constant) can change the output of f.

Returns:

list[int]: List of indices corresponding to the essential variables.

get_number_of_essential_variables() → int[source]

Count the number of essential variables in a Boolean function.

Returns:

int: The number of essential variables.

get_type_of_inputs() → ndarray[source]

Determine for each input of the Boolean function whether it is positive, negative, conditional or non-essential.

Returns:

np.ndarray[str]: The type of each input of the Boolean function.

get_symmetry_groups() → list[source]

Determine all symmetry groups of input variables for a Boolean function.

Two variables are in the same symmetry group if swapping their values does not change the output of the function for any input of the other variables.

Returns:

list[list[int]]: A list of lists where each inner list contains indices of variables that form a symmetry group.

get_absolute_bias() → float[source]

Compute the absolute bias of a Boolean function.

The absolute bias is defined as |(self.get_hamming_weight() / 2^(n-1)) - 1|, which quantifies how far the function’s output distribution deviates from being balanced.

Returns:

float: The absolute bias of the Boolean function.

get_activities(nsim: int = 10000, EXACT: bool = False, *, rng=None) → array[source]

Compute the activities of all variables of a Boolean function.

This function can compute the activities by exhaustively iterating over all inputs (if EXACT is True) or estimate it via Monte Carlo sampling (if EXACT is False).

Parameters:

nsim (int, optional): Number of random samples (default is 10000, used when EXACT is False).

EXACT (bool, optional): If True, compute the exact sensitivity by iterating over all inputs; otherwise, use sampling (default).

rng (None, optional): Argument for the random number generator, implemented in ‘utils._coerce_rng’.

Returns:

np.array(float): The activities of the variables of the Boolean function.

get_average_sensitivity(nsim: int = 10000, EXACT: bool = False, NORMALIZED: bool = True, *, rng=None) → float[source]

Compute the average sensitivity of a Boolean function.

The average sensitivity is equivalent to the Derrida value D(F,1) when the update rule is sampled from the same space. This function can compute the exact sensitivity by exhaustively iterating over all inputs (if EXACT is True) or estimate it via Monte Carlo sampling (if EXACT is False). The result can be normalized by the number of inputs.

Parameters:

nsim (int, optional): Number of random samples (default is 10000, used when EXACT is False).

EXACT (bool, optional): If True, compute the exact sensitivity by iterating over all inputs; otherwise, use sampling (default).

NORMALIZED (bool, optional): If True, return the normalized sensitivity (divided by the number of function inputs); otherwise, return the total count.

rng (None, optional): Argument for the random number generator, implemented in ‘utils._coerce_rng’.

Returns:

float: The (normalized) average sensitivity of the Boolean function.

get_layer_structure() → dict[source]

Determine the canalizing layer structure of a Boolean function.

This function decomposes a Boolean function into its canalizing layers (standard monomial form) by recursively identifying and removing conditionally canalizing variables. The output includes the canalizing depth, the number of layers, the canalizing inputs and outputs, the core function of the non-canalizing variables, and the order of the canalizing variables.

Returns:

dict: A dictionary (self.properties) containing:

CanalizingDepth (int): Canalizing depth (number of conditionally canalizing variables).

NumberOfLayers (int): Number of distinct canalizing layers.

CanalizingInputs (np.array[int]): Array of canalizing input values.

CanalizedOutputs (np.array[int]): Array of canalized output values.

CoreFunction (BooleanFunction): The core function (truth table) after removing canalizing variables. Inputs: non-canalizing variables.

OrderOfCanalizingVariables (np.array[int]): Array of indices representing the order of canalizing variables.

LayerStructure (np.array[int]): Indicates the number of variables in each canalizing layer.

References:

He, Q., & Macauley, M. (2016). Stratification and enumeration of Boolean functions by canalizing depth. Physica D: Nonlinear Phenomena, 314, 1-8.

Dimitrova, E., Stigler, B., Kadelka, C., & Murrugarra, D. (2022). Revealing the canalizing structure of Boolean functions: Algorithms and applications. Automatica, 146, 110630.

get_canalizing_depth() → int[source]

Returns the canalizing depth of the function.

Returns:

int: The canalizing depth (number of conditionally canalizing variables).

get_kset_canalizing_proportion(k: int) → float[source]

Compute the proportion of k-set canalizing input sets for a Boolean function.

For a given k, this function calculates the probability that a randomly chosen set of k inputs canalizes the function, i.e., forces the output regardless of the remaining variables.

Parameters:

k (int): The size of the variable set (0 ≤ k ≤ n).

Returns:

float: The proportion of k-set canalizing input sets.

References:

Kadelka, C., Keilty, B., & Laubenbacher, R. (2023). Collectively canalizing Boolean functions. Advances in Applied Mathematics, 145, 102475.

get_kset_canalizing_proportion_of_variables(k: int) → float[source]

Compute the proportion of k-set canalizing input sets that contain a specific variable.

For a given k, this function calculates the probability that a randomly chosen set of k inputs (including a specific variable) canalizes the function, i.e., forces the output regardless of the remaining variables.

Parameters:

k (int): The size of the variable set (0 ≤ k ≤ n).

Returns:

float: The proportion of k-set canalizing input sets.

References:

Kadelka, C., Keilty, B., & Laubenbacher, R. (2023). Collectively canalizing Boolean functions. Advances in Applied Mathematics, 145, 102475.

get_canalizing_strength() → tuple[source]

Compute the canalizing strength of a Boolean function via exhaustive enumeration.

The canalizing strength is defined as a weighted average of the proportions of k-set canalizing inputs for k = 1 to n-1. It is 0 for minimally canalizing functions (e.g., Boolean parity functions) and 1 for maximally canalizing functions (e.g., nested canalizing functions with one layer).

Returns:

The canalizing strength of f.

References:

Kadelka, C., Keilty, B., & Laubenbacher, R. (2023). Collectively canalizing Boolean functions. Advances in Applied Mathematics, 145, 102475.

get_canalizing_strength_of_variables() → tuple[source]

Compute the canalizing strength of each variable in a Boolean function via exhaustive enumeration.

The canalizing strength is defined as a weighted average of the proportions of k-set canalizing inputs for k = 1 to n-1. It is 0 for minimally canalizing functions (e.g., Boolean parity functions) and 1 for maximally canalizing functions (e.g., nested canalizing functions with one layer).

Returns:

np.array(float): The canalizing strength of each variable of f.

get_input_redundancy() → float | None[source]

Important

This method requires an installation of CANA (See Extended Functionality). If CANA is not found, this method will return None.

Compute the input redundancy of a Boolean function.

The input redundancy quantifies how many inputs are not required to determine the function’s output. Constant functions have an input redundancy of 1 (none of the inputs are needed), whereas parity functions have an input redundancy of 0 (all inputs are necessary).

Returns:

float: Normalized input redundancy in the interval [0, 1].

References:

Marques-Pita, M., & Rocha, L. M. (2013). Canalization and control in automata networks: body segmentation in Drosophila melanogaster. PloS One, 8(3), e55946.

Correia, R. B., Gates, A. J., Wang, X., & Rocha, L. M. (2018). CANA: a python package for quantifying control and canalization in Boolean networks. Frontiers in Physiology, 9, 1046.

get_edge_effectiveness() → list | None[source]

Important

This method requires an installation of CANA (See Extended Functionality). If CANA is not found, this method will return None.

Compute the edge effectiveness for each regulator of a Boolean function.

Edge effectiveness measures how much flipping a given input (regulator) influences the output. Non-essential inputs have an effectiveness of 0, whereas inputs that always flip the output when toggled have an effectiveness of 1.

Returns:

list[float]: A list of n floats in [0, 1] representing the edge effectiveness for each input.

References:

Marques-Pita, M., & Rocha, L. M. (2013). Canalization and control in automata networks: body segmentation in Drosophila melanogaster. PloS One, 8(3), e55946.

Correia, R. B., Gates, A. J., Wang, X., & Rocha, L. M. (2018). CANA: a python package for quantifying control and canalization in Boolean networks. Frontiers in Physiology, 9, 1046.

get_effective_degree() → float | None[source]

Important

This method requires an installation of CANA (See Extended Functionality). If CANA is not found, this method will return None.

Compute the effective degree, i.e., the sum of the edge effectivenesses of each regulator, of a Boolean function.

Edge effectiveness measures how much flipping a given input (regulator) influences the output. Non-essential inputs have an effectiveness of 0, whereas inputs that always flip the output when toggled have an effectiveness of 1.

Returns:

float: The sum of the edge effectiveness of each regulator.

References:

Marques-Pita, M., & Rocha, L. M. (2013). Canalization and control in automata networks: body segmentation in Drosophila melanogaster. PloS One, 8(3), e55946.

Correia, R. B., Gates, A. J., Wang, X., & Rocha, L. M. (2018). CANA: a python package for quantifying control and canalization in Boolean networks. Frontiers in Physiology, 9, 1046.