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}