001package org.biopax.paxtools.model.level3;
002
003import java.util.Set;
004
005/**
006 * Definition: A conversion interaction in which one or more entities (substrates) undergo covalent
007 * changes to become one or more other entities (products). The substrates of biochemical reactions
008 * are defined in terms of sums of species. This is convention in biochemistry, and, in principle,
009 * all of the EC reactions should be biochemical reactions. Examples: ATP + H2O = ADP + Pi Comment:
010 * In the example reaction above, ATP is considered to be an equilibrium mixture of several species,
011 * namely ATP4-, HATP3-, H2ATP2-, MgATP2-, MgHATP-, and Mg2ATP. Additional species may also need to
012 * be considered if other ions (e.g. Ca2+) that bind ATP are present. Similar considerations apply
013 * to ADP and to inorganic phosphate (Pi). When writing biochemical reactions, it is not necessary
014 * to attach charges to the biochemical reactants or to include ions such as H+ and Mg2+ in the
015 * equation. The reaction is written in the direction specified by the EC nomenclature system, if
016 * applicable, regardless of the physiological direction(s) in which the reaction proceeds.
017 * Polymerization reactions involving large polymers whose structure is not explicitly captured
018 * should generally be represented as unbalanced reactions in which the monomer is consumed but the
019 * polymer remains unchanged, e.g. glycogen + glucose = glycogen.
020 */
021public interface BiochemicalReaction extends Conversion
022{
023        /**
024         * Standard transformed Gibbs energy change for a reaction written in terms of biochemical
025         * reactants (sums of species), delta-G'<sup>o</sup>.
026         * 
027         * Since Delta-G can change based on multiple factors including ionic strength and temperature a
028         * reaction can have multiple DeltaG values.
029         * @return a set of DeltaG's for this reaction.
030         */
031        Set<DeltaG> getDeltaG();
032
033        /**
034         * Standard transformed Gibbs energy change for a reaction written in terms of biochemical
035         * reactants (sums of species), delta-G'<sup>o</sup>.
036         * 
037         * Since Delta-G can change based on multiple factors including ionic strength and temperature a
038         * reaction can have multiple DeltaG values.
039         * @param deltaG to be added.
040         */
041        void addDeltaG(DeltaG deltaG);
042
043        /**
044         * Standard transformed Gibbs energy change for a reaction written in terms of biochemical
045         * reactants (sums of species), delta-G'<sup>o</sup>.
046         * 
047         * Since Delta-G can change based on multiple factors including ionic strength and temperature a
048         * reaction can have multiple DeltaG values.
049         * @param deltaG to be removed.
050         */
051        void removeDeltaG(DeltaG deltaG);
052
053
054        /**
055         * For biochemical reactions this property refers to the standard transformed enthalpy change for a reaction
056         * written in terms of biochemical reactants (sums of species), delta-H'<sup>o</sup>.
057         * 
058         * delta-G'<sup>o</sup> = delta-H'<sup>o</sup> - T delta-S'<sup>o</sup>
059         * 
060         * Units: kJ/mole
061         * 
062         * @return standard transformed enthalpy change
063         */
064        Set<Float> getDeltaH();
065
066        /**
067         * For biochemical reactions this property refers to the standard transformed enthalpy change for a reaction
068         * written in terms of biochemical reactants (sums of species), delta-H'<sup>o</sup>.
069         * 
070         * delta-G'<sup>o</sup> = delta-H'<sup>o</sup> - T delta-S'<sup>o</sup>
071         * 
072         * Units: kJ/mole
073         * 
074         * @param delta_h standard transformed enthalpy change
075         */
076        void addDeltaH(float delta_h);
077
078        /**
079         * For biochemical reactions this property refers to the standard transformed enthalpy change for a reaction
080         * written in terms of biochemical reactants (sums of species), delta-H'<sup>o</sup>.
081         * 
082         * delta-G'<sup>o</sup> = delta-H'<sup>o</sup> - T delta-S'<sup>o</sup>
083         * 
084         * Units: kJ/mole
085         * 
086         * @param delta_h standard transformed enthalpy change
087         */
088        void removeDeltaH(float delta_h);
089
090
091        /**
092         * For biochemical reactions, this property refers to the standard transformed entropy change for a reaction
093         * written in terms of biochemical reactants (sums of species), delta-S'<sup>o</sup>.
094         * 
095         * delta-G'<sup>o</sup> = delta-H'<sup>o</sup> - T delta-S'<sup>o</sup>
096         * @return standard transformed entropy change
097         */
098        Set<Float> getDeltaS();
099
100        /**
101         * For biochemical reactions, this property refers to the standard transformed entropy change for a reaction
102         * written in terms of biochemical reactants (sums of species), delta-S'<sup>o</sup>.
103         * 
104         * delta-G'<sup>o</sup> = delta-H'<sup>o</sup> - T delta-S'<sup>o</sup>
105         * standard transformed entropy change
106         *
107         * @param delta_s value
108         */
109        void addDeltaS(float delta_s);
110
111        /**
112         * For biochemical reactions, this property refers to the standard transformed entropy change for a reaction
113         * written in terms of biochemical reactants (sums of species), delta-S'<sup>o</sup>.
114         * 
115         * delta-G'<sup>o</sup> = delta-H'<sup>o</sup> - T delta-S'<sup>o</sup>
116         * standard transformed entropy change
117         *
118         * @param delta_s value
119         */
120        void removeDeltaS(float delta_s);
121
122
123        /**
124         * The unique number assigned to a reaction by the Enzyme Commission of the International Union of Biochemistry
125         * and Molecular Biology.
126         * @return The unique number assigned to a reaction by the Enzyme Commission
127         */
128         Set<String> getECNumber();
129
130        /**
131         * The unique number assigned to a reaction by the Enzyme Commission of the International Union of Biochemistry
132         * and Molecular Biology.
133         * @param ec_number The unique number assigned to a reaction by the Enzyme Commission
134         */
135        void addECNumber(String ec_number);
136
137        /**
138         * The unique number assigned to a reaction by the Enzyme Commission of the International Union of Biochemistry
139         * and Molecular Biology.
140         * @param ec_number The unique number assigned to a reaction by the Enzyme Commission
141         */
142        void removeECNumber(String ec_number);
143
144
145        /**
146         * This quantity is dimensionless and is usually a single number. The measured equilibrium constant for a
147         * biochemical reaction, encoded by the slot KEQ, is actually the apparent equilibrium constant,
148         * K'.  Concentrations in the equilibrium constant equation refer to the total concentrations of  all forms of
149         * particular biochemical reactants. For example, in the equilibrium constant equation for the biochemical
150         * reaction in which ATP is hydrolyzed to ADP and inorganic phosphate:
151         * 
152         * K' = [ADP][P<sub>i</sub>]/[ATP],
153         * 
154         * The concentration of ATP refers to the total concentration of all of the following species:
155         * 
156         * [ATP] = [ATP<sup>4-</sup>] + [HATP<sup>3-</sup>] + [H<sub>2</sub>ATP<sup>2-</sup>] + [MgATP<sup>2-</sup>] +
157         * [MgHATP<sup>-</sup>] + [Mg<sub>2</sub>ATP].
158         * 
159         * The apparent equilibrium constant is formally dimensionless, and can be kept so by inclusion of as many of
160         * the terms (1 mol/dm<sup>3</sup>) in the numerator or denominator as necessary.  It is a function of
161         * temperature (T), ionic strength (I), pH, and pMg (pMg = -log<sub>10</sub>[Mg<sup>2+</sup>]). Therefore,
162         * these quantities must be specified to be precise, and values for KEQ for biochemical reactions may be
163         * represented as 5-tuples of the form (K' T I pH pMg).  This property may have multiple values,
164         * representing different measurements for K' obtained under the different experimental conditions listed in
165         * the 5-tuple.
166         * @return measured equilibrium constant for a biochemical reaction
167         */
168        Set<KPrime> getKEQ();
169
170        /**
171         * This quantity is dimensionless and is usually a single number. The measured equilibrium constant for a
172         * biochemical reaction, encoded by the slot KEQ, is actually the apparent equilibrium constant,
173         * K'.  Concentrations in the equilibrium constant equation refer to the total concentrations of  all forms of
174         * particular biochemical reactants. For example, in the equilibrium constant equation for the biochemical
175         * reaction in which ATP is hydrolyzed to ADP and inorganic phosphate:
176         * 
177         * K' = [ADP][P<sub>i</sub>]/[ATP],
178         * 
179         * The concentration of ATP refers to the total concentration of all of the following species:
180         * 
181         * [ATP] = [ATP<sup>4-</sup>] + [HATP<sup>3-</sup>] + [H<sub>2</sub>ATP<sup>2-</sup>] + [MgATP<sup>2-</sup>] +
182         * [MgHATP<sup>-</sup>] + [Mg<sub>2</sub>ATP].
183         * 
184         * The apparent equilibrium constant is formally dimensionless, and can be kept so by inclusion of as many of
185         * the terms (1 mol/dm<sup>3</sup>) in the numerator or denominator as necessary.  It is a function of
186         * temperature (T), ionic strength (I), pH, and pMg (pMg = -log<sub>10</sub>[Mg<sup>2+</sup>]). Therefore,
187         * these quantities must be specified to be precise, and values for KEQ for biochemical reactions may be
188         * represented as 5-tuples of the form (K' T I pH pMg).  This property may have multiple values,
189         * representing different measurements for K' obtained under the different experimental conditions listed in
190         * the 5-tuple.
191         * @param keq measured equilibrium constant for a biochemical reaction
192         */
193        void addKEQ(KPrime keq);
194
195        /**
196         * This quantity is dimensionless and is usually a single number. The measured equilibrium constant for a
197         * biochemical reaction, encoded by the slot KEQ, is actually the apparent equilibrium constant,
198         * K'.  Concentrations in the equilibrium constant equation refer to the total concentrations of  all forms of
199         * particular biochemical reactants. For example, in the equilibrium constant equation for the biochemical
200         * reaction in which ATP is hydrolyzed to ADP and inorganic phosphate:
201         * 
202         * K' = [ADP][P<sub>i</sub>]/[ATP],
203         * 
204         * The concentration of ATP refers to the total concentration of all of the following species:
205         * 
206         * [ATP] = [ATP<sup>4-</sup>] + [HATP<sup>3-</sup>] + [H<sub>2</sub>ATP<sup>2-</sup>] + [MgATP<sup>2-</sup>] +
207         * [MgHATP<sup>-</sup>] + [Mg<sub>2</sub>ATP].
208         * 
209         * The apparent equilibrium constant is formally dimensionless, and can be kept so by inclusion of as many of
210         * the terms (1 mol/dm<sup>3</sup>) in the numerator or denominator as necessary.  It is a function of
211         * temperature (T), ionic strength (I), pH, and pMg (pMg = -log<sub>10</sub>[Mg<sup>2+</sup>]). Therefore,
212         * these quantities must be specified to be precise, and values for KEQ for biochemical reactions may be
213         * represented as 5-tuples of the form (K' T I pH pMg).  This property may have multiple values,
214         * representing different measurements for K' obtained under the different experimental conditions listed in
215         * the 5-tuple.
216         * @param keq measured equilibrium constant for a biochemical reaction
217         */
218        void removeKEQ(KPrime keq);
219
220}