Struct biodivine_lib_param_bn::BooleanNetwork

pub struct BooleanNetwork { /* private fields */ }

A Boolean network, possibly parametrised with uninterpreted Boolean functions.

The structure of the network is based on an underlying RegulatoryGraph. However, compared to a RegulatoryGraph, BooleanNetwork can have a specific update function given for each variable.

If the function is not specified (so called implicit parametrisation), all admissible Boolean functions are considered in its place. A function can be also only partially specified by using declared explicit parameters. These are uninterpreted but named Boolean functions, such that, again, all admissible instantiations of these functions are considered. See crate tutorial to learn more.

Boolean network equivalence

Please keep in mind that we consider two networks to be equivalent when they share a regulatory graph, and when they have (syntactically) the same update functions and parameters. We do not perform any semantic checks for whether the update functions are functionally equivalent.

Also keep in mind that the ordering of variables and parameters must be shared by equivalent networks. This is because we want to preserve the property that VariableId and ParameterId objects are interchangeable as log as networks are equivalent.

Implementations

impl BooleanNetwork

pub fn try_from_sbml( model_file: &str ) -> Result<(BooleanNetwork, Layout), String>

Try to read a BooleanNetwork from an SBML string.

Also reads Layout information from the file. If there is no layout, an empty map is returned.

pub fn try_from_sbml_strict( model_file: &str, warnings: &mut Vec<String> ) -> Result<(BooleanNetwork, Layout), String>

The same as try_from_sbml, but provides access to all warnings generated during parsing.

These can be for example due to incompatibility in variable names (which the parser resolves automatically).

impl BooleanNetwork

pub fn to_sbml(&self, layout: Option<&Layout>) -> String

Convert this network to an SBML string with an optional Layout.

pub fn write_as_sbml( &self, layout: Option<&Layout>, out: &mut dyn Write ) -> Result<(), Error>

Write an SBML string representation (with an optional Layout) of this network to the given out writer.

impl BooleanNetwork

Methods for parsing BooleanNetworks from string representation.

pub fn add_string_update_function( &mut self, variable: &str, update_function: &str ) -> Result<(), String>

Add a new UpdateFunction to the BooleanNetwork. All variables and parameters must be already present in the network. Furthermore, all parameters must be used with their correct cardinality.

impl BooleanNetwork

Basic methods for safely building BooleanNetworks.

pub fn remove_static_constraints(&self) -> BooleanNetwork

Build a copy of this Boolean network where all essentiality and monotonicity constraints are removed. This is basically the “inverse” of BooleanNetwork::infer_valid_graph.

pub fn new(graph: RegulatoryGraph) -> BooleanNetwork

Construct a new BooleanNetwork from a RegulatoryGraph without any parameters.

pub fn try_from_file<T: AsRef<Path>>(path: T) -> Result<BooleanNetwork, String>

pub fn add_parameter( &mut self, name: &str, arity: u32 ) -> Result<ParameterId, String>

Add a new Parameter to the BooleanNetwork.

The parameter name must be different from other parameters and variables.

pub fn add_update_function( &mut self, variable: VariableId, function: FnUpdate ) -> Result<(), String>

Add a new UpdateFunction to the BooleanNetwork.

The variable must not already have an update function. We assume all the variables and parameters in the function are used correctly. If you are not sure how to safely build an instance of a FnUpdate, look at the variants of this method which parse the function safely from a string.

pub fn set_update_function( &mut self, variable: VariableId, function: Option<FnUpdate> ) -> Result<(), String>

Allows to directly replace (or remove) the update function.

The function will replace existing function (if any), but it still needs to satisfy the declared regulations.

impl BooleanNetwork

Some utility methods for accessing the structure of a BooleanNetwork. Some of them are just delegating to the internal RegulatoryGraph, but we have a copy here as well because they are used very often.

pub fn as_graph(&self) -> &RegulatoryGraph

Obtain a reference to the underlying RegulatoryGraph of the BooleanNetwork.

pub fn as_graph_mut(&mut self) -> &mut RegulatoryGraph

Obtain a mutable reference to the underlying RegulatoryGraph.

However, note that at the moment, you can’t really do much with this reference, only add new regulations.

pub fn num_vars(&self) -> usize

The number of variables in this BooleanNetwork.

pub fn num_parameters(&self) -> usize

The number of explicit parameters in this BooleanNetwork (there can be network variables using erased functions–implicit parameters–that are not counted here).

pub fn num_implicit_parameters(&self) -> usize

The number of variables with erased update functions in this BooleanNetwork.

pub fn variables(&self) -> VariableIdIterator

Return an iterator over all variable ids of this network.

pub fn get_variable(&self, id: VariableId) -> &Variable

Return the variable object based on the given VariableId.

pub fn get_variable_name(&self, id: VariableId) -> &String

Shorthand for self.as_graph().get_variable(id).get_name().

pub fn regulators(&self, target: VariableId) -> Vec<VariableId>

Return a sorted list of variables that regulate the given target variable.

pub fn targets(&self, regulator: VariableId) -> Vec<VariableId>

Return a sorted list of variables that are regulated by the given regulator variable.

pub fn find_parameter(&self, name: &str) -> Option<ParameterId>

Find a ParameterId corresponding to the given parameter name.

pub fn get_parameter(&self, id: ParameterId) -> &Parameter

Get a Parameter corresponding to the given ParameterId.

pub fn get_update_function(&self, variable: VariableId) -> &Option<FnUpdate>

Get a FnUpdate corresponding to the given VariableId.

pub fn parameters(&self) -> ParameterIdIterator

Return an iterator over all parameter ids of this network.

pub fn implicit_parameters(&self) -> Vec<VariableId>

Iterate over all variables of this network that do not have update functions assigned for them.

pub fn is_valid_name(name: &str) -> bool

A static check that allows to verify validity of a parameter or variable name.

pub fn parameter_appears_in( &self, parameter: ParameterId ) -> HashSet<VariableId>

Compute the set of network variables which depend (syntactically) on the given parameter.

pub fn prune_unused_parameters(&self) -> BooleanNetwork

Return a copy of this network where all unused parameters (uninterpreted functions) are removed.

Note that VariableId objects are still valid for the result network, but ParameterId objects can now refer to different parameters.

impl BooleanNetwork

pub fn infer_valid_graph(&self) -> Result<BooleanNetwork, String>

Infer a sufficient local regulatory graph based on the update functions of this BooleanNetwork.

Notes

• The method will simplify the update functions when it detects that a variable is not an essential input of the update function (for any instantiation).
• This also removes any unused parameters (uninterpreted functions), or parameters that become unused due to the transformation.
• For fully specified update functions, the method simply updates the regulations to match the actual behaviour of the function (i.e. any non-essential regulations are removed, monotonicity is always specified unless the input is truly non-monotonic).
• For regulations that interact with uninterpreted functions:
  • Observability: If there are no instantiations where the regulation is essential, we remove the regulation completely. Otherwise, we preserve the original observability constraint.
  • Monotonicity: Similarly, if every instantiation of the function has a known monotonicity, then we use this monotonicity. Otherwise, if the original constraint is still satisfied for a subset of all instantiations, we use the original one.

Limitations

The result only guarantees that the constraints are locally consistent*, meaning they are valid when applied to the singular update function, not necessarily the whole model. In other words, uninterpreted functions that are used by multiple variables can still cause the model to be invalid if they use contradictory constraints, but this usually cannot be resolved deterministically.

Output

The function can fail we, for whatever reason, cannot create SymbolicContext for the old network.

pub fn inline_constants( &self, infer_constants: bool, repair_graph: bool ) -> BooleanNetwork

Similar to BooleanNetwork::inline_inputs, but inlines constant values (i.e. x=true or x=false).

By default, the constant check is purely syntactic, but we do perform basic constant propagation (e.g. x | true = true) in order to catch the most obvious non-trivial cases. However, you can set infer_constants to true, in which case a symbolic method will be used to check if the variable uses a constant function. Note that this can also eliminate parameters in some cases (e.g. inlining x=true into y=x | f(z)).

Furthermore, similar to BooleanNetwork::inline_inputs, you can set repair_graph to true in order to fix any inconsistent regulations that arise due to the inlining (this is highly recommended if you are using infer_constants).

The inlining is performed iteratively, meaning if the inlining produces a new constant, it is eventually also inlined.

Panics

The method can fail if infer_constants or repair_graph is specified and the network does not have a valid symbolic representation.

pub fn inline_inputs( &self, infer_inputs: bool, repair_graph: bool ) -> BooleanNetwork

Try to inline the input nodes (variables) of the network as logical parameters (uninterpreted functions of arity 0).

Here, an “input” is a variable x such that:

• x has no incoming regulations and a missing update function.
• x has an identity update function. This is either checked syntactically (default), or semantically using BDDs (if infer_inputs is set to true).

Note that this does not include constant nodes (e.g. x=true). These are handled separately by BooleanNetwork::inline_constants. Also note that input variables that do not influence any other variable are removed.

Variables with update functions x=f(true, false) or x=a (where a is a zero-arity parameter) are currently not considered to be inputs, although their role is conceptually similar.

This method is equivalent to calling BooleanNetwork::inline_variable on each input, but the current implementation of BooleanNetwork::inline_variable does not permit inlining of self-regulating variables, hence we have a special method for inputs only.

Finally, just as BooleanNetwork::inline_variable, the method can generate an inconsistent regulatory graph. If repair_graph is set to true, the static properties of relevant regulations are inferred using BDDs.

pub fn inline_variable( &self, var: VariableId, repair_graph: bool ) -> Option<BooleanNetwork>

Produce a new BooleanNetwork where the given VariableId var has been eliminated by inlining its update function into all downstream variables.

Note that the inlining operation is purely syntactic. This means that even if we create new regulations when relevant, the resulting regulatory graph may be inconsistent with the update functions. If you set repair_graph to true, the method will perform semantic analysis on the new functions and repair regulatory graph where relevant. If repair_graph is set to false, the operation does not perform any post-processing.

A simple example where “inconsistent” regulatory graph is produced is the inlining of a constant input variable f_a = true into the update function f_c = a | b. Here, we have regulations a -> c and b -> c. However, for the inlined function, we have f_c = (true | b) = true. As such, b is no longer observable in f_c and the resulting model is thus not “logically consistent”. We need to either fix this manually, or using BooleanNetwork::infer_valid_graph.

Limitations

At the moment, the reduced variable cannot have a self-regulation. If such a variable is targeted with reduction, the result is None. If a variable is inlined into a missing function, the function is given a name as a new parameter, and the variable is inlined into this new parameter function.

Note that variables that don’t regulate anything (outputs) are simply removed by this reduction. However, this is correct behaviour, just not super intuitive.

Also note that because the set of variables is different between this and the resulting BooleanNetwork, any VariableId that is valid in this network is not valid in the resulting network.

Logical parameters

Finally, note the set of admissible parameter instantiations (interpretations of uninterpreted functions) can change between the original and the reduced model. The reason for this is the same as in the example of a “logically inconsistent” system described above. For example, consider a -> b and b -> c, but also a -| c. Then, let’s have f_b = f(a) and f_c = b & !a. Then f(a) = a is the only admissible interpretation of f. However, suppose we reduce variable b, obtaining f_c = f(a) & !a with regulation a -? c (because a -> b -> c and a -| c in the original system). Then f can actually be false, a, or !a.

This does not mean you cannot use reduction on systems with uninterpreted functions at all, but be careful about the new meaning of the static constraints on these functions.

impl BooleanNetwork

pub fn try_from_bnet(model_string: &str) -> Result<BooleanNetwork, String>

Try to load a Boolean network from a .bnet model.

Note that this is currently only a “best effort” implementation and you may encounter unsupported bnet models.

We also support some features that bnet does not, in particular, you can use Boolean constants. However, there are also other things that we do not support, since bnet can essentially use R syntax to define more complex functions, but in practice this is not used anywhere as far as I know.

impl BooleanNetwork

pub fn to_bnet(&self, rename_if_necessary: bool) -> Result<String, String>

Produce a .bnet string representation of this model.

Returns an error if the network is parametrised and thus cannot be converted to .bnet. Also returns an error if the network contains names which are not supported in .bnet, such as starting with numbers.

However, you can override this behaviour using rename_if_necessary. If this flag is set, all invalid names will be prefixed with _.

Trait Implementations

impl Clone for BooleanNetwork

fn clone(&self) -> BooleanNetwork

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BooleanNetwork

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for BooleanNetwork

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Index<ParameterId> for BooleanNetwork

Allow indexing BooleanNetwork using ParameterId objects.

type Output = Parameter

The returned type after indexing.

fn index(&self, index: ParameterId) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<VariableId> for BooleanNetwork

Allow indexing BooleanNetwork using VariableId objects.

type Output = Variable

The returned type after indexing.

fn index(&self, index: VariableId) -> &Self::Output

Performs the indexing (container[index]) operation.

impl PartialEq for BooleanNetwork

fn eq(&self, other: &BooleanNetwork) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<&str> for BooleanNetwork

type Error = String

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for BooleanNetwork

impl StructuralPartialEq for BooleanNetwork