001package org.biopax.paxtools.model.level3;
002
003import org.biopax.paxtools.util.AutoComplete;
004
005import java.util.Set;
006
007/**
008 * Definition: An entity reference is a grouping of several physical entities across different
009 * contexts and molecular states, that share common physical properties and often named and treated
010 * as a single entity with multiple states by biologists.
011 *
012 * Rationale:   Many protein, small molecule and gene databases share this point of view, and such a
013 * grouping is an important prerequisite for interoperability with those databases. Biologists would
014 * often group different pools of molecules in different contexts under the same name. For example
015 * cytoplasmic and extracellular calcium have different effects on the cell's behavior, but they are
016 * still called calcium. For DNA, RNA and Proteins the grouping is defined based on a wildtype
017 * sequence, for small molecules it is defined by the chemical structure.
018 *
019 * Usage: Entity references store the information common to a set of molecules in various states
020 * described in the BioPAX document, including database cross-references. For instance, the P53
021 * protein can be phosphorylated in multiple different ways. Each separate P53 protein (pool) in a
022 * phosphorylation state would be represented as a different protein (child of physicalEntity) and
023 * all things common to all P53 proteins, including all possible phosphorylation sites, the sequence
024 * common to all of them and common references to protein databases containing more information
025 * about P53 would be stored in a Entity Reference.
026 *
027 * Comments: This grouping has three semantic implications: <ol> <li>Members of different pools
028 * share many physical and biochemical properties. This includes their chemical structure, sequence,
029 * organism and set of molecules they react with. They will also share a lot of secondary
030 * information such as their names, functional groupings, annotation terms and database identifiers.
031 * <li> A small number of transitions seperates these pools. In other words it is relatively easy
032 * and frequent for a molecule to transform from one physical entity to another that belong to the
033 * same reference entity. For example an extracellular calcium can become cytoplasmic, and p53 can
034 * become phosphorylated. However no calcium virtually becomes sodium, or no p53 becomes mdm2. In
035 * the former it is the sheer energy barrier of a nuclear reaction, in the latter sheer statistical
036 * improbability of synthesizing the same sequence without a template. If one thinks about the
037 * biochemical network as molecules transforming into each other, and remove edges that respond to
038 * transcription, translation, degradation and covalent modification of small molecules, each
039 * remaining component is a reference entity. <li> Some of the pools in the same group can overlap.
040 * p53-p@ser15 can overlap with p53-p@thr18. Most of the experiments in molecular biology will only
041 * check for one state variable, rarely multiple, and never for the all possible combinations. So
042 * almost all statements that refer to the state of the molecule talk about a pool that can overlap
043 * with other pools. However no overlaps is possible between molecules of different groups. </ol>
044 */
045
046public interface EntityReference extends UtilityClass, Named, Observable
047{
048
049
050        /**
051         * Variable features that are observed for the entities of this entityReference - such as known PTM
052         * or methylation sites and non-covalent bonds. Note that this is an aggregate list of all known
053         * features and it does not represent a state itself.
054         *
055         * @return a set of entityFeatures
056         */
057        @AutoComplete(backward = true)
058        Set<EntityFeature> getEntityFeature();
059
060        /**
061         * Variable features that are observed for the entities of this entityReference - such as known PTM
062         * or methylation sites and non-covalent bonds. Note that this is an aggregate list of all known
063         * features and it does not represent a state itself.
064         *
065         * @param feature to be added.
066         */
067        void addEntityFeature(EntityFeature feature);
068
069        /**
070         * Variable features that are observed for the entities of this entityReference - such as known PTM
071         * or methylation sites and non-covalent bonds. Note that this is an aggregate list of all known
072         * features and it does not represent a state itself.
073         *
074         * @param feature to be removed.
075         */
076        void removeEntityFeature(EntityFeature feature);
077
078
079        /**
080         * Inverse of {@link SimplePhysicalEntity#getEntityReference()}
081         *
082         * @return a  set of {@link SimplePhysicalEntity} that has this EntityReference
083         */
084        Set<SimplePhysicalEntity> getEntityReferenceOf();
085
086
087        /**
088         * @return Controlled vocabulary terms that is used to describe the type of grouping such as
089         *         homology or functional group.
090         */
091        Set<EntityReferenceTypeVocabulary> getEntityReferenceType();
092
093        /**
094         * Adds the given cv to the list of types
095         *
096         * @param type A controlled vocabulary term that is used to describe the type of grouping such as
097         *             homology or functional group.
098         */
099        void addEntityReferenceType(EntityReferenceTypeVocabulary type);
100
101        /**
102         * Removes the given cv from the list of types
103         *
104         * @param type A controlled vocabulary term that is used to describe the type of grouping such as
105         *             homology or functional group.
106         */
107        void removeEntityReferenceType(EntityReferenceTypeVocabulary type);
108
109
110        /**
111         * @return Entity references that qualifies for the definition of this group. For example a member
112         *         of a PFAM protein family.
113         */
114        Set<EntityReference> getMemberEntityReference();  //todo generify?
115
116/**
117         * Adds the given entityReference to the member list
118         *
119         * @param entityReference An entity reference that qualifies for the definition of this group. For
120         *                        example a member of a PFAM protein family.
121         */
122        void addMemberEntityReference(EntityReference entityReference);
123
124        /**
125         * Removes the given entityReference from the member list
126         *
127         * @param entityReference An entity reference that qualifies for the definition of this group. For
128         *                        example a member of a PFAM protein family.
129         */
130        void removeMemberEntityReference(EntityReference entityReference);
131
132        /**
133         * Reverse of {@link #getMemberEntityReference()}
134         *
135         * @return EntityReferences that this EntityReference is a member of.
136         */
137        public Set<EntityReference> getMemberEntityReferenceOf();
138
139}