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}