Struct biodivine_lib_param_bn::RegulatoryGraph

pub struct RegulatoryGraph {
    pub(crate) variables: Vec<Variable>,
    pub(crate) regulations: Vec<Regulation>,
    pub(crate) variable_to_index: HashMap<String, VariableId>,
}

A directed graph representing relationships between a collection of Boolean variables using Regulations.

It can be explored using regulators, targets, transitive_regulators, or transitive_targets (for example to determine if two variables depend on each other). We can also compute the SCCs of this graph.

A regulatory graph can be described using a custom string format. In this format, each line represents a regulation or a comment (starting with #).

Regulations can be represented as strings in the form of "regulator_name 'relationship' target_name". The ‘relationship’ is one of the arrow strings ->, ->?, -|, -|?, -?, -??. Here, > means activation, | is inhibition and ? is unspecified monotonicity. The last question mark signifies observability — if it is present, the regulation is not necessarily observable. See Regulation and tutorial module for a more detailed explanation.

Example of a RegulatoryGraph:

 a ->? a
 b -|? a

 a -> b
 b -| b

Fields

variables: Vec<Variable>

regulations: Vec<Regulation>

variable_to_index: HashMap<String, VariableId>

Implementations

impl RegulatoryGraph

Methods for parsing RegulatoryGraphs from string representations.

pub fn try_from_string_regulations(
    regulations: Vec<String>
) -> Result<RegulatoryGraph, String>

Create a RegulatoryGraph from a collection of regulation strings.

The variables of the RegulatoryGraph are determined from the regulations and are ordered alphabetically. Otherwise, this is equivalent to iteratively calling add_string_regulation.

pub fn add_string_regulation(&mut self, regulation: &str) -> Result<(), String>

Add a new Regulation to this RegulatoryGraph where the regulation is given in its string representation (e.g. “v1 ->? v2”).

The regulation parameter must be a valid string representation of a regulation, plus all conditions of add_regulation must be satisfied as well.

pub(crate) fn add_temp_regulation(
    &mut self,
    regulation: RegulationTemp
) -> Result<(), String>

(internal) A utility method for adding regulations once they are parsed.

impl RegulatoryGraph

Methods for safely constructing new instances of RegulatoryGraphs.

pub fn new(variables: Vec<String>) -> RegulatoryGraph

Create a new RegulatoryGraph with variables using the given names and no regulations.

The ordering of the variables is preserved.

pub fn add_regulation(
    &mut self,
    regulator: &str,
    target: &str,
    observable: bool,
    monotonicity: Option<Monotonicity>
) -> Result<(), String>

Add a new Regulation to this RegulatoryGraph.

Returns Err if regulator or target are not valid graph variables or when the regulation between the two variables already exists.

pub fn set_variable_name(
    &mut self,
    id: VariableId,
    name: &str
) -> Result<(), String>

Set the name of a network variable. The name must not be used by any other variable.

Note that you don’t have to rename anything else in the network, since all other structures reference variables with ids.

fn get_regulator(&self, name: &str) -> Result<VariableId, String>

(internal) Utility method to safely obtain a regulator variable (using an appropriate error message).

fn get_target(&self, name: &str) -> Result<VariableId, String>

(internal) Utility method to safely obtain a target variable (using an appropriate error message).

fn assert_no_regulation(
    &self,
    regulator: VariableId,
    target: VariableId
) -> Result<(), String>

(internal) Utility method to ensure there is no regulation between the two variables yet.

impl RegulatoryGraph

Some basic utility methods for inspecting the RegulatoryGraph.

pub fn num_vars(&self) -> usize

The number of variables in this RegulatoryGraph.

pub fn find_variable(&self, name: &str) -> Option<VariableId>

Find a VariableId for the given name, or None if the variable does not exist.

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

Return a Variable corresponding to the given VariableId.

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

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

pub fn find_regulation(
    &self,
    regulator: VariableId,
    target: VariableId
) -> Option<&Regulation>

Find a Regulation between two variables if it exists, None otherwise.

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

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

pub fn transitive_regulators(&self, target: VariableId) -> HashSet<VariableId>

Return the set of direct as well as transitive regulators of target.

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

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

pub fn transitive_targets(&self, regulator: VariableId) -> HashSet<VariableId>

Return a set of direct as well as transitive targets of regulator.

pub fn components(&self) -> Vec<HashSet<VariableId>>

Compute the strongly connected components of this regulatory graph. The components are sorted topologically based on their position in the graph condensation.

When sorting topologically incomparable components, we use component size as the secondary criterion. Also, note that the algorithm is not particularly efficient, so it should be used on large networks with caution!

pub fn variables(&self) -> VariableIdIterator

Return an iterator over all variable ids of this graph.

pub fn regulations(&self) -> RegulationIterator<'_>

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

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

impl RegulatoryGraph

pub fn to_dot(&self) -> String

Export this regulatory graph to a .dot format.

In the representation, we use red and green color to distinguish positive and negative regulations. Dashed edges show regulations without observability requirement.

pub fn write_as_dot(&self, output: &mut dyn Write) -> Result<(), Error>

Trait Implementations

impl Clone for RegulatoryGraph

fn clone(&self) -> RegulatoryGraph

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RegulatoryGraph

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

Formats the value using the given formatter.

impl Display for RegulatoryGraph

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

Formats the value using the given formatter.

impl Index<VariableId> for RegulatoryGraph

Allow indexing RegulatoryGraph 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<RegulatoryGraph> for RegulatoryGraph

To consider two regulatory graphs equivalent, we generally assume that they have the same number of variables, with the same names, and stored in the same order. Furthermore, they also need to have the same regulations, however, these do not have a specific order that needs to be preserved. The reason why we enforce variable order and not regulation order is that VariableId objects should be compatible across equivalent graphs, but there is no RegulationId or a similar requirement.

fn eq(&self, other: &Self) -> 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 !=.

impl TryFrom<&'_ str> for RegulatoryGraph

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 RegulatoryGraph