Boolean Function

Created on Tue Aug 12 11:03:49 2025

@author: Benjamin Coberly, Claus Kadelka

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

Bases: object

A class representing a Boolean function.

Constructor Parameters:

  • f (list | np.array | 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): 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): 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): Dynamically created dictionary with additional information about the function (canalizing layer structure, type of inputs, etc.)

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

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_degenerated() → bool[source]

Determine if a Boolean function contains non-essential variables.

A variable is non-essential if the function’s output does not depend on it.

Returns:

  • bool: True if f contains at least one non-essential variable, False if all variables are essential.

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: 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 of str: The type of each input of the Boolean function.

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.

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: 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_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.

Returns:

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

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 (core function) 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:

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

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

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): Array of canalizing input values.

    • CanalizedOutputs (np.array): Array of canalized output values.

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

    • OrderOfCanalizingVariables (np.array): Array of indices representing the order of canalizing variables.

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

References:

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

  2. 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:

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

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:

  1. 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:

  • tuple:

    • float: The canalizing strength of f.

    • list: A list of the k-set canalizing proportions for k = 1, 2, …, n-1.

References:

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

get_input_redundancy() → float | None[source]

Important

This method requires an installation of CANA (See Extended Functionality). If CANA is not found, this method wil 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:

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

  2. 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 wil 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: A list of n floats in [0, 1] representing the edge effectiveness for each input.

References:

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

  2. 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 wil 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:

  • list: A value in [0, 1] representing the effective degree for each input. #TODO

References:

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

  2. 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.