circuitree.models.SimpleNetworkGrammar

A Grammar class for pairwise interaction networks.

This class models a circuit as a set of components and pairwise interactions. This grammar is well-suited for simple biological networks such as basic transcriptional networks or signaling pathways where regulation between components is pairwise.

Each state of circuit assembly is encoded as a string that contains the components and interactions in the circuit, and each action can either add a new interaction or terminate the assembly.

A component is abbreviated by an uppercase letter. For instance, Mdm2 and p53 would be M and P, respectively). Multiple components are concatenated (MP).
Each type of interaction is abbreviated as a lowercase letter. For instance, activation and inhibition would be abbreviated as a and i.
Each pairwise interaction is represented by three characters, the two components involved and the type of interaction. For instance, MPi means “MdM2 inhibits p53”. Multiple interactions are separated by _.
The state is a two-part string <components>::<interactions>.
A terminal state starts with *.

For example, the state string *MP::MPi_PMa represents the MdM2-p53 negative feedback circuit, where MdM2 inhibits p53 and p53 activates MdM2. The * indicates that the circuit has been fully assembled.

Parameters:

components (str | Iterable[str]) – _description_
interactions (str | Iterable[str]) – _description_
max_interactions (int, optional) – The maximum number of interactions allowed in a state. Defaults to len(components) ** 2.
root (str, optional) – The initial state.
fixed_components (Optional[str | Iterable[str]], optional) – A list of components to ignore when computing uniqueness. In other words, these components are considered fixed and will not be permuted when computing unique states.
cache_maxsize (int | None, optional) – The maximum size of the LRU cache used to speed up the computation of unique states. Defaults to 128.

Raises:

ValueError – If the first character of any component or interaction type is not unique.

Models a circuit as a set of components and with pairwise interactions. Each state of circuit assembly is encoded as a string with the following format:

__init__(components: str | Iterable[str], interactions: str | Iterable[str], max_interactions: int | None = None, root: str | None = None, fixed_components: list[str] | None = None, cache_maxsize: int | None = 128, *args, **kwargs)

Methods

`__init__`(components, interactions[, ...])
`do_action`(genotype, action)	Applies the given action to the current circuit assembly state, or `genotype`.
`get_actions`(genotype)	Returns the actions that can be taken from a given `state`, or `genotype`.
`get_component_recolorings`(components)	Returns all possible recolorings of the components in a given state.
`get_recolorings`(genotype)	Returns all possible recolorings (equivalent string representations) of a given state.
`get_undo_actions`(genotype)	(Experimental) Get all actions that can be undone from the given state.
`get_unique_state`(genotype)	Returns a unique representation of a given state.
`has_pattern`(state, pattern)	Checks if a given state contains a particular sub-pattern.
`is_terminal`(genotype)	Checks if the given assembly state (`genotype`) is a terminal state.
`parse_genotype`(genotype[, nonterminal_ok])	Parses a genotype string into its components, activations, and inhibitions.
`to_dict`()	Convert the grammar to a dictionary that can be serialized to JSON.
`undo_action`(genotype, action)	(Experimental) Undo one action from the given state.

Attributes

component_codes

Set of single-character uppercase component codes.

do_action(genotype: str, action: str) → str

Applies the given action to the current circuit assembly state, or genotype.

The action can be:

A single character: Add a new component to the circuit.
Three characters: Add a new interaction between two components.
*terminate*: Terminate the assembly process.

Parameters:

genotype (str) – The current assembly state.
action (str) – The action to be applied.

Returns:

The new state (genotype) after applying the action to given state.

Return type:

str

Examples

>>> grammar = SimpleNetworkGrammar(...)
>>> gen1 = "MP::"  # Initial state with two components
>>> gen2 = grammar.do_action(gen1, "MPi")  # Add inhibition interaction
>>> print(gen2)
"MP::MPi"
>>> gen3 = grammar.do_action(gen2, "Q")  # Add a new component
>>> print(gen3)
"MPQ::MPi"
>>> gen4 = grammar.do_action(gen3, "*terminate*")  # Terminate the assembly
>>> grammar.is_terminal(gen4)
True

get_actions(genotype: str) → Iterable[str]

Returns the actions that can be taken from a given state, or genotype.

Possible actions are adding a new component, adding a new interaction, or terminating the assembly process. Checks to make sure the necessary components are present and the circuit would remain fully connected.

Parameters:: genotype (str) – The current state of the circuit assembly.
Returns:: A list of valid actions that can be taken.
Return type:: Iterable[str]

get_component_recolorings(components: str) → list[str]: Returns all possible recolorings of the components in a given state.

get_recolorings(genotype: str) → Iterable[str]: Returns all possible recolorings (equivalent string representations) of a given state.

get_undo_actions(genotype: str) → Iterable[str]: (Experimental) Get all actions that can be undone from the given state.

get_unique_state(genotype: str) → str

Returns a unique representation of a given state.

This method is used to determine whether two state IDs represent the same topology, after accounting for component renaming and reording of the interactions. For example, different sequences of actions may lead to different state IDs that are isomorphic mirror images, or “recolorings” of each other. This method picks the alphabetically first representation over all possible recolorings.

Parameters:: genotype (str) – The current state.
Returns:: The unique representation of the state.
Return type:: str

has_pattern(state: str, pattern: str)

Checks if a given state contains a particular sub-pattern.

The pattern should be a string that contains only interactions (separated by underscores) and no components. This method checks if the interactions in the pattern are a subset of the interactions in the given state.

Parameters:

state (str) – The current state.
pattern (str) – The sub-pattern to search for.

Returns:

Whether the state contains the given pattern.

Return type:

bool

Raises:

ValueError – If the pattern contains components or if the state does not contain both components and interactions.

static is_terminal(genotype: str) → bool

Checks if the given assembly state (genotype) is a terminal state. A terminal state starts with an asterisk *.

Parameters:: genotype (str) – An assembly state.
Returns:: Whether the state is terminal.
Return type:: bool

static parse_genotype(genotype: str, nonterminal_ok: bool = False)

Parses a genotype string into its components, activations, and inhibitions.

Parameters:

genotype (str) – The genotype string to parse.
nonterminal_ok (bool, optional) – Whether to allow non-terminal genotypes. Defaults to False.

Returns:

The components, activations, and: inhibitions in the genotype. The activations and inhibitions are represented as numpy arrays with two columns, where each row is a pair of indices representing the interacting components.

Return type:

tuple[str, np.ndarray, np.ndarray]

Raises:

ValueError – If the genotype is nonterminal and nonterminal_ok is False.

to_dict() → dict

Convert the grammar to a dictionary that can be serialized to JSON. Useful for saving the grammar to a file or for transferring it over a network.

The __grammar_cls__ key is added to the dictionary to indicate the name of the class that should be used to re-instantiate the grammar.

Returns:: A dictionary representation of the grammar.
Return type:: dict

undo_action(genotype: str, action: str) → str: (Experimental) Undo one action from the given state.

property component_codes: set[str]: Set of single-character uppercase component codes.