= Introduction to ScrumPy =

This is a very brief introduction to {{{ScrumPy}}}, with emphasis on structural analysis. A more complete documentation can be found [[ScrumPy/Doc | here]].

== Loading and defining models ==

A pre-existing model is loaded by creating an instance of {{{ScrumPy.Model(model)}}} with {{{model}}} being the name of the model file (string-type ending with the {{{ScrumPy}}} file extension, {{{.spy}}}), provided that the model file is stored in the directory from where the {{{ScrumPy}}} shell was launched. If no name is provided, a GUI for selecting a model to open, is launched.



{{{#!python
>>> m = ScrumPy.Model('toy_model.spy')
}}}

This will open a new empty editor window, copy and paste the model description below. Having done that, select "compile" from the "ScrumPy" menu, and the model is loaded.

Where {{{toy_model.spy}}} is a small structural model:

{{{#! python
Structural()

A_tx:
    x_A -> A
    ~

R_1:
    A -> B
    ~

R_2:
    B -> C
    ~

R_3:
    C -> E
    ~

R_4:
    B -> D
    ~

R_5:
    D -> E
    ~

R_6:
    D -> F
    ~

E_tx:
    E -> x_E
    ~

}}}

The reactions with the suffix "{{{_tx}}}" are transporters, i.e. they convert external metabolites (with prefix "{{{x_}}}") to internal metabolites. 

== Properties of structural models ==

The class {{{Model}}} has a range of methods, of which some are only useful for kinetic models (which are also structural models, but the oposite is not true). Among the structurally relevant methods we find {{{ConsMoieties()}}} - which prints a list of conserved moieties; {{{DeadReactions()}}} - which returns a list of reactions that cannot carry steady state flux; {{{FindIsoforms()}}} - which identifies reactions from the model that are redundant, i.e. a set of reactions have identical stoichiometry; {{{ElModes()}}} - which returns an elementary modes object; {{{Externals()}}} - which returns a list of external metabolites.

=== The stoichiometry matrix ===

The fields {{{Model.sm}}} and {{{Model.smexterns}}} are the two stoichiometry matrices assocciated with a model - the former is the internal matrix, the latter the external. The external matrix contains infomation about external metabolites, whereas the internal does not. All instances of {{{ScrumPy}}} matrices (subclasses of {{{DynMatrix}}}) have the fields {{{cnames}}} - column names and {{{rnames}}} - row names.

{{{#!python
>>> m.sm.cnames
['R_1', 'R_2', 'R_3', 'R_4', 'R_5', 'R_6', 'E_tx', 'A_tx']
>>> m.sm.rnames                #but m.smexterns.rnames will be longer
['A', 'B', 'C', 'E', 'D', 'F']
}}}

Useful methods of {{{sm}}} (and {{{smexterns}}}) include {{{ReacToStr(reac)}}},
{{{#!python
>>> print m.sm.ReacToStr('R_2')
R_2:
	1/1 B -> 1/1 C
	~

}}}

and  {{{InvolvedWith(name)}}},
{{{#!python
>>> m.sm.InvolvedWith('R_2')
{'C': mpq(1,1), 'B': mpq(-1,1)}
>>> m.sm.InvolvedWith('C')
{'R_2': mpq(1,1), 'R_3': mpq(-1,1)}
}}}

=== Reaction reversibility ===

{{{ScrumPy}}} accepts three reversibility symbols: {{{"->"}}} - left to right irreversible, {{{"<-"}}} - right to left irreversible, and {{{<>}}} - reversible. Reaction reversibility is handled by the stoichiometry matrix.

{{{#!python
>>> m.sm.GetIrrevs()
['R_1', 'R_2', 'R_3', 'R_4', 'R_5', 'R_6', 'E_tx', 'A_tx']
>>> m.sm.MakeRevers('R_2')      
>>> m.sm.GetIrrevs()
['R_1', 'R_3', 'R_4', 'R_5', 'R_6', 'E_tx', 'A_tx']
>>> m.Reload()

>>> m.sm.GetIrrevs()
['R_1', 'R_2', 'R_3', 'R_4', 'R_5', 'R_6', 'E_tx', 'A_tx']
}}}

== Nullspace analysis ==

The kernel of the stoichiometry matrix can be calculated using the {{{sm.NullSpace()}}} method ({{{smexterns}}} also has the method, but the kernel of the external matrix is only related to the futile cycles of the model, not possible steady-state solutions). 

{{{#!python
>>> k = m.sm.NullSpace()
>>> k
    c_0 c_1 

 R_1 -1/1  0/1 
 R_2 -1/1  1/1 
 R_3 -1/1  1/1 
 R_4 0/1  -1/1 
 R_5 0/1  -1/1 
 R_6 0/1  0/1 
 E_tx -1/1  0/1 
 A_tx -1/1  0/1 
}}}

Even if the signs of some of the coeffients indicate thermodynamically infeasible solutions (e.g. all active reactions in the first column have negative coefficients, even though they are irreversible) a lot of useful information can be obtained form {{{k}}}. For instance, we see that the row associated with {{{R_6}}} is a null-vector, indicating that there is no steady-state solution involving {{{R_6}}}. In fact this is how {{{ScrumPy}}} detects dead reactions with the method {{{DeadReactions()}}}.

{{{#!python
>>> m.DeadReactions()
['R_6']
}}}

Also, note that some of the row-vectors are proportional to each other - {{{R_2}}}, {{{R_3}}}; {{{R_4}}}, {{{R_5}}}; and {{{E_tx}}}, {{{A_tx}}}, {{{R_1}}}. This implies that these sets must carry flux in a coordinated fashion, e.g. any flux solution involving {{{R_4}}} must also involve {{{R_5}}}. These sets of coordinated reactions are referred to as ''enzyme subsets'' and can be determined using the {{{Model}}} method {{{EnzSubsets()}}}. This method returns a dictionary object where keys are subset names (or reaction name if a reaction is in a singleton set) and values are nested dictionaries where keys are reaction names and values are the flux ratios of the reactions. The key {{{DeadReacs}}} maps to a list of dead reactions.

{{{#!python
>>> ess=m.EnzSubsets()
>>> ess
{'Ess_3': {'R_4': mpq(-1,1), 'R_5': mpq(-1,1)}, 'Ess_2': {'R_2': mpq(1,1), 'R_3': mpq(1,1)}, 'Ess_1': {'E_tx': mpq(1,1), 'R_1': mpq(1,1), 'A_tx': mpq(1,1)}, 'DeadReacs': {'R_6': mpq(1,1)}}
}}}

The elementary modes of a model can be analysed using the method {{{Model.ElModes()}}}. The field {{{mo}}} is a matrix similar to {{{k}}}.
{{{#!python
>>> elmo = m.ElModes()
>>> elmo.mo
    ElMo_0 ElMo_1 

 R_1 1/1  1/1 
 R_2 1/1  0/1 
 R_3 1/1  0/1 
 R_4 0/1  1/1 
 R_5 0/1  1/1 
 R_6 0/1  0/1 
 E_tx 1/1  1/1 
 A_tx 1/1  1/1 
}}}

The relationship between modes and metabolites is stored in the {{{sto}}} matrix.
{{{#!python
>>> elmo.sto
    ElMo_0 ElMo_1 

 x_A -1/1  -1/1 
 A 0/1  0/1 
 B 0/1  0/1 
 C 0/1  0/1 
 E 0/1  0/1 
 D 0/1  0/1 
 F 0/1  0/1 
 x_E 1/1  1/1 
}}}

The methods {{{Modes()}}} and {{{Stos()}}} returns a string with with same information as the matrices above.
{{{#!python
>>> print elmo.Modes()
ElMo_0, 1/1 E_tx, 1/1 R_1, 1/1 R_2, 1/1 R_3, 1/1 A_tx

ElMo_1, 1/1 E_tx, 1/1 R_1, 1/1 A_tx, 1/1 R_4, 1/1 R_5

>>> print elmo.Stos()
ElMo_0:
	1/1 x_A -> 1/1 x_E
	~
ElMo_1:
	1/1 x_A -> 1/1 x_E
	~
}}}