Pattern matching against PySB models (pysb.pattern)

class pysb.pattern.FilterPredicate

Base class for building predicates

For use with pysb.core.ComponentSet.filter().

class pysb.pattern.Function(regex)

Predicate to filter a ComponentSet by function where components are defined

class pysb.pattern.Module(regex)

Predicate to filter a ComponentSet by module where components are defined

class pysb.pattern.Name(regex)

Predicate to filter a ComponentSet by regular expression name search

Note that this uses re.search which matches anywhere in the component name. Use ^ to explicitly anchor the match to the beginning.

class pysb.pattern.Pattern(pattern)

Predicate to filter a ComponentSet by matching a ComplexPattern

See pysb.core.ComponentSet.filter() for examples.

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

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: kf21*__s15*__s45 - kr21*__s47
    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: kc20*__s46
    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: kc21*__s47
    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: kf28*__s51*__s7 - kr28*__s53
    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: kc21*__s47
    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: kf20*__s14*__s45 - kr20*__s46
    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: kc20*__s46
    Rules: [Rule('produce_ACytoC_via_AMito', AMito(b=1) % mCytoC(b=1) >>
            AMito(b=None) + ACytoC(b=None), kc20)]]

class pysb.pattern.RulePatternMatcher(model)

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)

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)

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

Parameters:

speciesComplexPattern

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

check_duplicatebool, 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)

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)

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)

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)

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)

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:

patComplexPattern, 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)

Return the list of integer bond numbers used in a pattern

To return as a set, use get_bonds_in_pattern().

Parameters:

patComplexPattern, 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)

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)

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)

Return the set of monomers used in a pattern