001package org.biopax.paxtools.model.level3;
002
003import java.util.Set;
004
005/**
006 * Definition: An interaction in which molecules of one or more {@link PhysicalEntity} pools are physically
007 * transformed and become a member of one or more other PhysicalEntity pools.
008 * 
009 * Rationale: Conversion and pools of entities are two central abstractions of chemistry. They can be quantized with
010 * rate and concentration respectively. A conversion in BioPAX, similar to chemistry,
011 * is stoichiometric and closed world, i.e. it is assumed that all of the participants are listed. These properties
012 * are due to the law of mass conservation. This differs from Control for example where multiple entities might be
013 * controlling the controlled and everything that is not listed is assumed to be unknown. Conversions in BioPAX can
014 * be reversible -- the property names Left and Right were preferred specifically because they are direction neutral
015 * as opposed to substrate and product or input and output.
016 * 
017 * Usage: Subclasses of conversion represent different types of transformation reflected by the properties of
018 * different physicalEntity. {@link BiochemicalReaction}s will change the {@link ModificationFeature}s on a
019 * {@link PhysicalEntity}, {@link Transport} will change the Cellular Location and {@link ComplexAssembly} will
020 * change {@link BindingFeature}s. Generic Conversion class should only be used when the modification does not fit
021 * into a any of these classes.
022 * 
023 * Example: Opening of a voltage gated channel.
024 */
025public interface Conversion extends Interaction
026{
027
028
029        /**
030         * The participants on the left side of the conversion interaction. Since conversion interactions may proceed
031         * in either the left-to-right or right-to-left direction, occupants of the left property may be either
032         * reactants or products. left is a sub-property of participants.
033         * @return The participants on the left side of the conversion interaction.
034         */
035        public Set<PhysicalEntity> getLeft();
036
037        /**
038         * Adds a participant to the left side of the conversion interaction. Since conversion interactions may proceed
039         * in either the left-to-right or right-to-left direction, occupants of the left property may be either
040         * reactants or products. left is a sub-property of participants.
041         * @param left participants to be added to the left side of the conversion interaction.
042         */
043        void addLeft(PhysicalEntity left);
044
045        /**
046         * Removes a participant from the left side of the conversion interaction. Since conversion interactions may
047         * proceed
048         * in either the left-to-right or right-to-left direction, occupants of the left property may be either
049         * reactants or products. left is a sub-property of participants.
050         * @param left participants to be removed from the left side of the conversion interaction.
051         */
052        void removeLeft(PhysicalEntity left);
053
054
055        /**
056         * Stoichiometry of the left ({@link #getLeft()}) and right({@link #getRight()}) participants.
057         * Note: This is a "bridge" workaround for the n-ary relationship problem. There is no default stoichiometry (
058         * e.g. 1). Leaving this out will create reactions with unknown stoichiometry.
059         * It is a best practice to define the stoichiometry of each participant.
060         * It is invalid to define more than one stoichiometry per participant.
061         * It is invalid to reuse stoichiometry instances across conversions.
062         * @return Stoichiometry of the left ({@link #getLeft()}) and right({@link #getRight()}) participants.
063         */
064        Set<Stoichiometry> getParticipantStoichiometry();
065
066        /**
067         * This method adds a stoichiometry for one of the participants of this conversion.
068         * @param stoichiometry to be added
069         */
070        void addParticipantStoichiometry(Stoichiometry stoichiometry);
071
072        /**
073         * This method removes a stoichiometry for one of the participants of this conversion.
074         * @param stoichiometry to be removed
075         */
076        void removeParticipantStoichiometry(Stoichiometry stoichiometry);
077
078
079        // Property RIGHT
080
081        /**
082         * The participants on the right side of the conversion interaction. Since conversion interactions may proceed
083         * in either the right-to-right or right-to-right direction, occupants of the right property may be either
084         * reactants or products. right is a sub-property of participants.
085         * @return The participants on the right side of the conversion interaction.
086         */
087        public Set<PhysicalEntity> getRight();
088
089        /**
090         * Adds a participant to the right side of the conversion interaction. Since conversion interactions may proceed
091         * in either the right-to-right or right-to-right direction, occupants of the right property may be either
092         * reactants or products. right is a sub-property of participants.
093         * @param right participants to be added to the right side of the conversion interaction.
094         */
095        void addRight(PhysicalEntity right);
096
097        /**
098         * Removes a participant from the right side of the conversion interaction. Since conversion interactions may
099         * proceed
100         * in either the right-to-right or right-to-right direction, occupants of the right property may be either
101         * reactants or products. right is a sub-property of participants.
102         * @param right participants to be removed from the right side of the conversion interaction.
103         */
104        void removeRight(PhysicalEntity right);
105
106
107        /**
108         * Specifies whether a conversion occurs spontaneously or not.
109         * 
110         * If the spontaneity is not known,this property should not be specified.
111         * @return whether if this conversion is spontaneous.
112         */
113        public Boolean getSpontaneous();
114
115        /**
116         * Specifies whether a conversion occurs spontaneously or not.
117         * 
118         * If the spontaneity is not known,this property should not be specified.
119         * @param spontaneous Whether if this conversion is spontaneous.
120         */
121        public void setSpontaneous(Boolean spontaneous);
122
123
124        /**
125         * This property represents the direction of the reaction. If a reaction will run in a single direction under
126         * all biological contexts then it is considered irreversible and has a direction. Otherwise it is reversible.
127         * @return One of REVERSIBLE, LEFT-TO-RIGHT or RIGHT-TO-LEFT
128         */
129        public ConversionDirectionType getConversionDirection();
130
131        /**
132         * This property represents the direction of the reaction. If a reaction will run in a single direction under
133         * all biological contexts then it is considered irreversible and has a direction. Otherwise it is reversible.
134         * @param conversionDirection One of REVERSIBLE, LEFT-TO-RIGHT or RIGHT-TO-LEFT --  null for unknown.
135         */
136        public void setConversionDirection(ConversionDirectionType conversionDirection);
137
138
139
140
141}