001package org.biopax.paxtools.model.level3;
002
003
004import java.util.Set;
005
006/**
007 * Description: A characteristic of a physical entity that can change while the entity still retains its biological
008 * identity.
009 * 
010 * Rationale: Two phosphorylated forms of a protein are strictly speaking different chemical  molecules. It is,
011 * however, standard in biology to treat them as different states of the same entity,
012 * where the entity is loosely defined based on sequence. Entity Feature class and its subclassses captures these
013 * variable characteristics. A Physical Entity in BioPAX represents a pool of  molecules rather than an individual
014 * molecule. This is a notion imported from chemistry (See {@link PhysicalEntity}). Pools are defined by a set of
015 * Entity Features in the sense that a single molecule must have all of the features in the set in order to be
016 * considered a member of the pool. Since it is impossible to list and experimentally test all potential features for
017 * an  entity, features that are not listed in the selection criteria is neglected Pools can also be defined by the
018 * converse by specifying features  that are known to NOT exist in a specific context. As DNA,
019 * RNA and Proteins can be hierarchically organized into families based on sequence homology so can entity features.
020 * The memberFeature property allows capturing such hierarchical classifications among entity features.
021 * 
022 * Usage: Subclasses of entity feature describe most common biological instances and should be preferred whenever
023 * possible. One common use case for instantiating  entity feature is, for describing active/inactive states of
024 * proteins where more specific feature information is not available.
025 * 
026 * Examples: Open/close conformational state of channel proteins, "active"/"inactive" states,
027 * excited states of photoreactive groups.
028 */
029public interface EntityFeature extends UtilityClass, Observable
030{
031
032        /**
033         * Inverse of {@link EntityReference#getEntityFeature()}
034         * @return the EntityReference that this EntityFeature belongs to.
035         */
036        EntityReference getEntityFeatureOf();
037
038
039        /**
040         * Inverse of {@link PhysicalEntity#getFeature()}
041         * Contents of this set is generated automatically and should not be modified.
042         * @return The list of PhysicalEntities that were observed to have this feature.
043         */
044        Set<PhysicalEntity> getFeatureOf();
045
046        /**
047         * Inverse of {@link PhysicalEntity#getNotFeature()}
048         * Contents of this set is generated automatically and should not be modified.
049         * @return The list of PhysicalEntities that were observed to NOT have this feature.
050         */
051        Set<PhysicalEntity> getNotFeatureOf();
052
053
054        /**
055         * Location of the feature on the sequence of the interactor.
056         * 
057         * For modification features this is the modified base or residue. For binding features this is the
058         * binding site and for fragment features this is the location of the fragment on the "base" sequence.
059         * 
060         * One feature may have more than one location, used e.g. for features which involve sequence positions close in
061         * the folded, three-dimensional state of a protein, but non-continuous along the sequence.
062         * 
063         * Small Molecules can have binding features but currently it is not possible to define the binding site on the
064         * small molecules. In those cases this property should not be specified.
065         * @return Location of the feature on the sequence of the interactor.
066         */
067        SequenceLocation getFeatureLocation();
068
069        /**
070         * Location of the feature on the sequence of the interactor.
071         * 
072         * For modification features this is the modified base or residue. For binding features this is the
073         * binding site and for fragment features this is the location of the fragment on the "base" sequence.
074         * 
075         * One feature may have more than one location, used e.g. for features which involve sequence positions close in
076         * the folded, three-dimensional state of a protein, but non-continuous along the sequence.
077         * 
078         * Small Molecules can have binding features but currently it is not possible to define the binding site on the
079         * small molecules. In those cases this property should not be specified.
080         * @param sequenceLocation of the feature
081         */
082        void setFeatureLocation(SequenceLocation sequenceLocation);
083
084        /**
085         * A controlled vocabulary term describing the type of the sequence location such as C-Terminal or SH2 Domain.
086         * Using Sequence Ontology (<a href ="http://www.sequenceontology.org">http://www.sequenceontology.org</a>) is
087         * recommended.
088         * @return A CV term describing the location of the feature
089         */
090        SequenceRegionVocabulary getFeatureLocationType();
091
092        /**
093         * A controlled vocabulary term describing the type of the sequence location such as C-Terminal or SH2 Domain.
094         * Using Sequence Ontology (<a href ="http://www.sequenceontology.org">http://www.sequenceontology.org</a>) is
095         * recommended.
096         * @param regionVocabulary A CV term describing the location of the feature
097         */
098        void setFeatureLocationType(SequenceRegionVocabulary regionVocabulary);
099
100
101        /**
102         * An entity feature  that belongs to this homology grouping.
103         * 
104         * Members of this set should be of the same class of this EntityFeature.
105         * 
106         * Members of this set should be an EntityFeature of an EntityReference which is a memberEntityReference of the
107         * EntityReference of this feature.
108         * 
109         * If this set is not empty than the sequenceLocation of this feature should be null.
110         * 
111         * Example: a homologous phosphorylation site across a protein family.
112         * @return An entity feature  that belongs to this homology grouping.
113         */
114        Set<EntityFeature> getMemberFeature();   //todo generify?
115
116        /**
117         * An entity feature  that belongs to this homology grouping.
118         * 
119         * Members of this set should be of the same class of this EntityFeature.
120         * 
121         * Members of this set should be an EntityFeature of an EntityReference which is a memberEntityReference of the
122         * EntityReference of this feature.
123         * 
124         * If this set is not empty than the sequenceLocation of this feature should be null.
125         * 
126         * Example: a homologous phosphorylation site across a protein family.
127         * @param entityFeature An entity feature  that belongs to this homology grouping.
128         */
129        void addMemberFeature(EntityFeature entityFeature);
130
131        /**
132         * An entity feature  that belongs to this homology grouping.
133         * 
134         * Members of this set should be of the same class of this EntityFeature.
135         * 
136         * Members of this set should be an EntityFeature of an EntityReference which is a memberEntityReference of the
137         * EntityReference of this feature.
138         * 
139         * If this set is not empty than the sequenceLocation of this feature should be null.
140         * 
141         * Example: a homologous phosphorylation site across a protein family.
142         * @param entityFeature An entity feature that belongs to this homology grouping.
143         */
144        void removeMemberFeature(EntityFeature entityFeature);
145
146        /**
147         * @param that EntityFeature to be compared
148         * @return returns true iff the given feature is at the equivalent sequence location with this feature
149         */
150        boolean atEquivalentLocation(EntityFeature that);
151
152        /**
153         * Reverse of {@link #getMemberFeature()}
154         * @return the generic feature(s) that this feature belong to
155         */
156        Set<EntityFeature> getMemberFeatureOf();
157}