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}