Pattern matching against PySB models (pysb.pattern)

class pysb.pattern.ReactionPatternMatcher(model, species_pattern_matcher=None)[source]

Match a pattern against a model’s reactions list

Methods are provided to match against reaction reactants, products or both. Searches can be Monomers, MonomerPatterns, ComplexPatterns or ReactionPatterns.

Examples

Create a PatternMatcher for the EARM 1.0 model

>>> from pysb.examples.earm_1_0 import model
>>> from pysb.bng import generate_equations
>>> from pysb.pattern import ReactionPatternMatcher
>>> generate_equations(model)
>>> rpm = ReactionPatternMatcher(model)

Assign some monomers to variables (only needed when importing a model instead of defining one interactively)

>>> AMito, mCytoC, mSmac, cSmac = [model.monomers[m] for m in                                        ('AMito', 'mCytoC', 'mSmac', 'cSmac')]

Search using a Monomer

>>> rpm.match_products(mSmac) 
[Rxn (reversible):
    Reactants: {'__s15': mSmac(b=None), '__s45': AMito(b=None)}
    Products: {'__s47': AMito(b=1) % mSmac(b=1)}
    Rate: __s15*__s45*kf21 - __s47*kr21
    Rules: [Rule('bind_mSmac_AMito', AMito(b=None) + mSmac(b=None) |
            AMito(b=1) % mSmac(b=1), kf21, kr21)]]

Search using a MonomerPattern

>>> rpm.match_reactants(AMito(b=ANY)) 
[Rxn (one-way):
    Reactants: {'__s46': AMito(b=1) % mCytoC(b=1)}
    Products: {'__s45': AMito(b=None), '__s48': ACytoC(b=None)}
    Rate: __s46*kc20
    Rules: [Rule('produce_ACytoC_via_AMito', AMito(b=1) % mCytoC(b=1) >>
            AMito(b=None) + ACytoC(b=None), kc20)],
 Rxn (one-way):
    Reactants: {'__s47': AMito(b=1) % mSmac(b=1)}
    Products: {'__s45': AMito(b=None), '__s49': ASmac(b=None)}
    Rate: __s47*kc21
    Rules: [Rule('produce_ASmac_via_AMito', AMito(b=1) % mSmac(b=1) >>
            AMito(b=None) + ASmac(b=None), kc21)]]
>>> rpm.match_products(cSmac(b=ANY)) 
[Rxn (reversible):
    Reactants: {'__s7': XIAP(b=None), '__s51': cSmac(b=None)}
    Products: {'__s53': XIAP(b=1) % cSmac(b=1)}
    Rate: __s51*__s7*kf28 - __s53*kr28
    Rules: [Rule('inhibit_cSmac_by_XIAP', cSmac(b=None) + XIAP(b=None) |
            cSmac(b=1) % XIAP(b=1), kf28, kr28)]]

Search using a ComplexPattern

>>> rpm.match_reactants(AMito() % mSmac()) 
[Rxn (one-way):
    Reactants: {'__s47': AMito(b=1) % mSmac(b=1)}
    Products: {'__s45': AMito(b=None), '__s49': ASmac(b=None)}
    Rate: __s47*kc21
    Rules: [Rule('produce_ASmac_via_AMito', AMito(b=1) % mSmac(b=1) >>
            AMito(b=None) + ASmac(b=None), kc21)]]
>>> rpm.match_reactions(AMito(b=3) % mCytoC(b=3))     
[Rxn (reversible):
    Reactants: {'__s14': mCytoC(b=None), '__s45': AMito(b=None)}
    Products: {'__s46': AMito(b=1) % mCytoC(b=1)}
    Rate: __s14*__s45*kf20 - __s46*kr20
    Rules: [Rule('bind_mCytoC_AMito', AMito(b=None) + mCytoC(b=None) |
            AMito(b=1) % mCytoC(b=1), kf20, kr20)],
 Rxn (one-way):
    Reactants: {'__s46': AMito(b=1) % mCytoC(b=1)}
    Products: {'__s45': AMito(b=None), '__s48': ACytoC(b=None)}
    Rate: __s46*kc20
    Rules: [Rule('produce_ACytoC_via_AMito', AMito(b=1) % mCytoC(b=1) >>
            AMito(b=None) + ACytoC(b=None), kc20)]]
class pysb.pattern.RulePatternMatcher(model)[source]

Match a pattern against a model’s species list

Methods are provided to match against rule reactants, products or both. Searches can be Monomers, MonomerPatterns, ComplexPatterns or ReactionPatterns.

Examples

Create a PatternMatcher for the EARM 1.0 model

>>> from pysb.examples.earm_1_0 import model
>>> from pysb.pattern import RulePatternMatcher
>>> rpm = RulePatternMatcher(model)

Assign some monomers to variables (only needed when importing a model instead of defining one interactively)

>>> AMito, mCytoC, mSmac, cSmac = [model.monomers[m] for m in         ('AMito', 'mCytoC', 'mSmac', 'cSmac')]

Search using a Monomer

>>> rpm.match_reactants(AMito) 
[Rule('bind_mCytoC_AMito', AMito(b=None) + mCytoC(b=None) |
    AMito(b=1) % mCytoC(b=1), kf20, kr20),
Rule('produce_ACytoC_via_AMito', AMito(b=1) % mCytoC(b=1) >>
    AMito(b=None) + ACytoC(b=None), kc20),
Rule('bind_mSmac_AMito', AMito(b=None) + mSmac(b=None) |
    AMito(b=1) % mSmac(b=1), kf21, kr21),
Rule('produce_ASmac_via_AMito', AMito(b=1) % mSmac(b=1) >>
    AMito(b=None) + ASmac(b=None), kc21)]
>>> rpm.match_products(mSmac) 
[Rule('bind_mSmac_AMito', AMito(b=None) + mSmac(b=None) |
    AMito(b=1) % mSmac(b=1), kf21, kr21)]

Search using a MonomerPattern

>>> rpm.match_reactants(AMito(b=1)) 
[Rule('produce_ACytoC_via_AMito', AMito(b=1) % mCytoC(b=1) >>
    AMito(b=None) + ACytoC(b=None), kc20),
Rule('produce_ASmac_via_AMito', AMito(b=1) % mSmac(b=1) >>
    AMito(b=None) + ASmac(b=None), kc21)]
>>> rpm.match_rules(cSmac(b=1)) 
[Rule('inhibit_cSmac_by_XIAP', cSmac(b=None) + XIAP(b=None) |
    cSmac(b=1) % XIAP(b=1), kf28, kr28)]

Search using a ComplexPattern

>>> rpm.match_reactants(AMito() % mSmac()) 
[Rule('produce_ASmac_via_AMito', AMito(b=1) % mSmac(b=1) >>
    AMito(b=None) + ASmac(b=None), kc21)]
>>> rpm.match_rules(AMito(b=1) % mCytoC(b=1))         
[Rule('bind_mCytoC_AMito', AMito(b=None) + mCytoC(b=None) |
    AMito(b=1) % mCytoC(b=1), kf20, kr20),
Rule('produce_ACytoC_via_AMito', AMito(b=1) % mCytoC(b=1) >>
    AMito(b=None) + ACytoC(b=None), kc20)]

Search using a ReactionPattern

>>> rpm.match_reactants(mCytoC() + mSmac())
[]
>>> rpm.match_reactants(AMito() + mCytoC()) 
[Rule('bind_mCytoC_AMito', AMito(b=None) + mCytoC(b=None) |
    AMito(b=1) % mCytoC(b=1), kf20, kr20)]
class pysb.pattern.SpeciesPatternMatcher(model, species=None)[source]

Match a pattern against a model’s species list

Examples

Create a PatternMatcher for the EARM 1.0 model

>>> from pysb.examples.earm_1_0 import model
>>> from pysb.bng import generate_equations
>>> from pysb.pattern import SpeciesPatternMatcher
>>> from pysb import ANY, WILD, Model, Monomer, as_complex_pattern
>>> generate_equations(model)
>>> spm = SpeciesPatternMatcher(model)

Assign two monomers to variables (only needed when importing a model instead of defining one interactively)

>>> Bax4 = model.monomers['Bax4']
>>> Bcl2 = model.monomers['Bcl2']

Search using a Monomer

>>> spm.match(Bax4)
[Bax4(b=None), Bax4(b=1) % Bcl2(b=1), Bax4(b=1) % Mito(b=1)]
>>> spm.match(Bcl2) 
[Bax2(b=1) % Bcl2(b=1),
Bax4(b=1) % Bcl2(b=1),
Bcl2(b=None),
Bcl2(b=1) % MBax(b=1)]

Search using a MonomerPattern (ANY and WILD keywords can be used)

>>> spm.match(Bax4(b=WILD))
[Bax4(b=None), Bax4(b=1) % Bcl2(b=1), Bax4(b=1) % Mito(b=1)]
>>> spm.match(Bcl2(b=ANY))
[Bax2(b=1) % Bcl2(b=1), Bax4(b=1) % Bcl2(b=1), Bcl2(b=1) % MBax(b=1)]

Search using a ComplexPattern

>>> spm.match(Bax4(b=1) % Bcl2(b=1))
[Bax4(b=1) % Bcl2(b=1)]
>>> spm.match(Bax4() % Bcl2())
[Bax4(b=1) % Bcl2(b=1)]

Contrived example to test a site with both a bond and state defined

>>> model = Model(_export=False)
>>> A = Monomer('A', ['a'], {'a': ['u', 'p']}, _export=False)
>>> model.add_component(A)
>>> species = [                                                                 A(a='u'),                                                               A(a=1) % A(a=1),                                                        A(a=('u', 1)) % A(a=('u', 1)),                                          A(a=('p', 1)) % A(a=('p', 1))                                       ]
>>> model.species = [as_complex_pattern(sp) for sp in species]
>>> spm2 = SpeciesPatternMatcher(model)
>>> spm2.match(A()) 
[A(a='u'), A(a=1) % A(a=1), A(a=('u', 1)) % A(a=('u', 1)),
 A(a=('p', 1)) % A(a=('p', 1))]
>>> spm2.match(A(a='u'))
[A(a='u')]
>>> spm2.match(A(a=('u', ANY)))
[A(a=('u', 1)) % A(a=('u', 1))]
>>> spm2.match(A(a=('u', WILD)))
[A(a='u'), A(a=('u', 1)) % A(a=('u', 1))]
add_species(species, check_duplicate=True)[source]

Add a species to the search list without adding to the model

Parameters:
species : ComplexPattern

A concrete ComplexPattern (molecular species) to add to the search list

check_duplicate : bool, optional

If True, check the species list to make sure the new species is not already in the list

match(pattern, index=False, exact=False, counts=False)[source]

Match a pattern against the list of species

Parameters:
pattern: pysb.Monomer or pysb.MonomerPattern or pysb.ComplexPattern
index: bool

If True, return species numerical index, rather than species itself

exact: bool

Treat Match as exact equivalence, not a pattern match (i.e. must be concrete if a MonomerPattern or ComplexPattern)

counts: bool

If True, return match counts for the search pattern within each species.

Returns:
list of pysb.ComplexPattern or list of int

A list of species matching the pattern is returned, unless index=True, in which case a list of the numerical indices of matching species is returned instead

Examples

>>> from pysb.examples import earm_1_0
>>> from pysb.bng import generate_equations
>>> model = earm_1_0.model
>>> generate_equations(model)
>>> spm = SpeciesPatternMatcher(model)
>>> L = model.monomers['L']
>>> spm.match(L())
[L(b=None), L(b=1) % pR(b=1)]
rule_firing_species(rules_to_consider=None, include_reverse=True)[source]

Return the species which match the reactants of a set of rules

Parameters:
rules_to_consider: list of pysb.Rule or None

A list of rules to use. If None, use all rules in the model.

include_reverse: bool, optional

For reversible rules, include species triggering the rule in reverse

Returns:
collections.OrderedDict

Dictionary of PySB rules whose reactants contain at least one of the species in the model. Keys are PySB rules, values are a list of lists. Each outer list corresponding to each ComplexPattern in the ReactantPattern (or ReactantPattern and ProductPattern, if rule is reversible). Each inner list contains the list of species matching the corresponding ComplexPattern.

Examples

>>> from pysb.examples import robertson
>>> from pysb.bng import generate_equations
>>> model = robertson.model
>>> generate_equations(model)
>>> spm = SpeciesPatternMatcher(model)

Get a list of species which fire each rule:

>>> spm.rule_firing_species()                 
OrderedDict([(Rule('A_to_B', A() >> B(), k1), [[A()]]),
 (Rule('BB_to_BC', B() + B() >> B() + C(), k2), [[B()], [B()]]),
 (Rule('BC_to_AC', B() + C() >> A() + C(), k3), [[B()], [C()]])])
species_fired_by_reactant_pattern(reaction_pattern)[source]

Get list of species matching a reactant pattern

Parameters:
reaction_pattern: pysb.ReactionPattern
Returns:
list of lists of pysb.ComplexPattern

List of lists of species matching each ComplexPattern in the ReactantPattern.

Examples

>>> from pysb.examples import bax_pore
>>> from pysb.bng import generate_equations
>>> model = bax_pore.model
>>> generate_equations(model)
>>> spm = SpeciesPatternMatcher(model)

Get a list of species which fire each rule:

>>> rxn_pat = model.rules['bax_dim'].reactant_pattern
>>> print(rxn_pat)
BAX(t1=None, t2=None) + BAX(t1=None, t2=None)
>>> spm.species_fired_by_reactant_pattern(rxn_pat)                 
[[BAX(t1=None, t2=None, inh=None),
  BAX(t1=None, t2=None, inh=1) % MCL1(b=1)],
 [BAX(t1=None, t2=None, inh=None),
      BAX(t1=None, t2=None, inh=1) % MCL1(b=1)]]
pysb.pattern.check_dangling_bonds(pattern)[source]

Check for dangling bonds in a PySB ComplexPattern/ReactionPattern

Raises a DanglingBondError if a dangling bond is found

pysb.pattern.get_bonds_in_pattern(pat)[source]

Return the set of integer bond numbers used in a pattern

To return as a list (with duplicates), use get_half_bonds_in_pattern()

Parameters:
pat : ComplexPattern, MonomerPattern, or None

A pattern from which bond numberings are extracted

Returns:
set

Bond numbers used in the supplied pattern

Examples

>>> A = Monomer('A', ['b1', 'b2'], _export=False)
>>> get_bonds_in_pattern(A(b1=None, b2=None)) == set()
True
>>> get_bonds_in_pattern(A(b1=1) % A(b2=1)) == {1}
True
>>> get_bonds_in_pattern(A(b1=1) % A(b1=2, b2=1) % A(b1=2)) == {1, 2}
True
pysb.pattern.get_half_bonds_in_pattern(pat)[source]

Return the list of integer bond numbers used in a pattern

To return as a set, use get_bonds_in_pattern().

Parameters:
pat : ComplexPattern, MonomerPattern, or None

A pattern from which bond numberings are extracted

Returns:
list

Bond numbers used in the supplied pattern

Examples

>>> A = Monomer('A', ['b1', 'b2'], _export=False)
>>> get_half_bonds_in_pattern(A(b1=None, b2=None))
[]
>>> get_half_bonds_in_pattern(A(b1=1) % A(b2=1))
[1, 1]
pysb.pattern.match_complex_pattern(pattern, candidate, exact=False, count=False)[source]

Compare two ComplexPatterns against each other

Parameters:
pattern: pysb.ComplexPattern
candidate: pysb.Complex.Pattern
exact: bool

Set to True for exact matches (i.e. species equivalence, or exact graph isomorphism). Set to False to compare as a pattern (i.e. subgraph isomorphism).

count: bool

Provide match counts for pattern in candidate

Returns:
True if pattern matches candidate, False otherwise
pysb.pattern.match_reaction_pattern(pattern, candidate)[source]

Compare two ReactionPatterns against each other

This function tests that every ComplexPattern in pattern has a matching ComplexPattern in candidate. If there’s a one-to-one mapping of ComplexPattern matches, this is straightforward. Otherwise, we need to check for a maximum matching - a graph theory term referring to the maximum number of edges possible in a bipartite graph (representing ComplexPattern compatibility between pattern and candidate) without overlapping nodes. If every ComplexPattern in pattern has a match, then return True, otherwise return False. This algorithm is polynomial time (although the ComplexPattern isomorphism comparisons using match_complex_pattern are not).

Parameters:
pattern: pysb.ReactionPattern
candidate: pysb.ReactionPattern
Returns:
True if pattern matches candidate, False otherwise.
pysb.pattern.monomers_from_pattern(pattern)[source]

Return the set of monomers used in a pattern