## org.biojava.bio.seq
Interface Feature

All Superinterfaces:
  Annotatable, Changeable, FeatureHolder

All Known Subinterfaces:
  ComponentFeature, FramedFeature, HomologyFeature, RemoteFeature, RestrictionSite, RichFeature, SimilarityPairFeature, StrandedFeature

All Known Implementing Classes:
  ProjectedFeature, SimpleFeature, SimpleFramedFeature, SimpleHomologyFeature, SimpleRemoteFeature, SimpleRestrictionSite, SimpleRichFeature, SimpleSimilarityPairFeature, SimpleStrandedFeature

    public interface Feature

extends FeatureHolder, Annotatable

A feature within a sequence, or nested within another feature.

## Common operations

     // loop over all features in a sequence
     for(Iterator fi = mySeq.features(); fi.hasNext(); ) {
       Feature f = (Feature) fi.next();
       System.out.println(f.getType() + "\t" + f.getLocation());
     }

     // loop over all features that are children of this one, such as exons in a
     // gene
     for(Iterator cfi = feature.features(); cfi.hasNext(); ) {
       ...

     // extract all stranded features that are directly on a sequence
     FeatureHolder strandedFeatures = mySeq.filter(
       new FeatureFilter.ByClass(StrandedFeature.class),
       false
      );
     for(fi = strandedFeatures.features(); ...

     // find all features with the type property set to "EXON" no matter how
     // far down the feature hierachy they are
     FeatureHolder repeats = mySeq.filter(
       new FeatureFilter.ByType("EXON"),
       true;
     );

## Description

Features contain annotation and a location. The type of the feature is something like 'Repeat' or 'BetaStrand'. Where the feature has been read from an EMBL or Genbank source the type will be the same as the feature key in the feature table e.g. 'gene', 'CDS', 'repeat_unit', 'misc_feature'. The source of the feature is something like 'genscan', 'repeatmasker' or 'made-up'.

Features are always contained by a parent `FeatureHolder`, which may either be a `Sequence` or another `Feature`. Feature instances should never be constructed directly by client code, and the BioJava core does not contain any publicly accessible implementations of the `Feature` interface. Instead, you should create a suitable `Feature.Template`, then pass this to the `createFeature` method of a `Sequence` or `Feature`.

We may need some standardisation for what the fields mean. In particular, we should be compliant where sensible with GFF.

Author:
  Matthew Pocock, Thomas Down, Keith James
See Also:
  `RichFeature`

Nested Class Summary
`static class` `Feature.ByLocationComparator` `ByLocationComparator` compares `Feature`s by the minimum base position of their `Location`.
`static class` `Feature.Template` Template class for a plain feature.

Nested classes/interfaces inherited from interface org.biojava.bio.seq.FeatureHolder
`FeatureHolder.EmptyFeatureHolder`

Nested classes/interfaces inherited from interface org.biojava.bio.Annotatable
`Annotatable.AnnotationForwarder`

Field Summary
`static Feature.ByLocationComparator` `byLocationOrder` `byLocationOrder` contains a `Feature` comparator which compares by the minimum base position of their `Location`.
`static ChangeType` `LOCATION` The location of this feature is being altered.
`static String` `PROPERTY_DATA_KEY` This is used as a key in the `Annotation` where it identifies internal data.
`static ChangeType` `SOURCE` The source of this feature has altered
`static ChangeType` `SOURCETERM` The ontological source of this feature has altered
`static ChangeType` `TYPE` The type of this feature has altered.
`static ChangeType` `TYPETERM` The ontological type of this feature has altered.

Fields inherited from interface org.biojava.bio.seq.FeatureHolder
`EMPTY_FEATURE_HOLDER, FEATURES, SCHEMA`

Fields inherited from interface org.biojava.bio.Annotatable
`ANNOTATION`

Method Summary
`Iterator` `features()` Iterate over any child features which are held by this feature.
`Location` `getLocation()` The location of this feature.
`FeatureHolder` `getParent()` Return the `FeatureHolder` to which this feature has been attached.
`Sequence` `getSequence()` Return the `Sequence` object to which this feature is (ultimately) attached.
`String` `getSource()` The source of the feature.
`Term` `getSourceTerm()` An ontology term defining the source of this feature.
`SymbolList` `getSymbols()` Return a list of symbols that are contained in this feature.
`String` `getType()` The type of the feature.
`Term` `getTypeTerm()` An ontology term defining the type of feature.
`Feature.Template` `makeTemplate()` Create a new Template that could be used to generate a feature identical to this one.
`void` `setLocation(Location loc)` The new location for this feature.
`void` `setSource(String source)` Change the source of the Feature.
`void` `setSourceTerm(Term t)` Set the source ontology-term for this feature.
`void` `setType(String type)` Change the type of this feature.
`void` `setTypeTerm(Term t)` Set the type ontology-term for this feature.

Methods inherited from interface org.biojava.bio.seq.FeatureHolder
`containsFeature, countFeatures, createFeature, filter, filter, getSchema, removeFeature`

Methods inherited from interface org.biojava.utils.Changeable
`addChangeListener, addChangeListener, isUnchanging, removeChangeListener, removeChangeListener`

Methods inherited from interface org.biojava.bio.Annotatable
`getAnnotation`

Methods inherited from interface org.biojava.utils.Changeable
`addChangeListener, addChangeListener, isUnchanging, removeChangeListener, removeChangeListener`

Field Detail

### PROPERTY_DATA_KEY

    static final String PROPERTY_DATA_KEY

  This is used as a key in the `Annotation` where it identifies internal data. This is not printed when the `Feature` is written to a flatfile. E.g. the original feature's EMBL location string (if it has one) is stored here.

  See Also:
    Constant Field Values

### LOCATION

    static final ChangeType LOCATION

  The location of this feature is being altered.

### TYPE

    static final ChangeType TYPE

  The type of this feature has altered.

### SOURCE

    static final ChangeType SOURCE

  The source of this feature has altered

### TYPETERM

    static final ChangeType TYPETERM

  The ontological type of this feature has altered.

### SOURCETERM

    static final ChangeType SOURCETERM

  The ontological source of this feature has altered

### byLocationOrder

    static final Feature.ByLocationComparator byLocationOrder

  `byLocationOrder` contains a `Feature` comparator which compares by the minimum base position of their `Location`.

Method Detail

### getLocation

    Location getLocation()

  The location of this feature.

  The location may be complicated, or simply a range. The annotation is assumed to apply to all the region contained within the location.

  Returns:
    a Location anchoring this feature

### setLocation

    void setLocation(Location loc)
                     throws ChangeVetoException

  The new location for this feature.

  The location may be complicated or simply a range. The annotation is assumed to apply to the entire region contained within the location. Any values returned from methods that rely on the old location must not be affected.

  Parameters:
    `loc` - the new Location for this feature
  Throws:
    `ChangeVetoException` - if the location can't be altered

### getType

    String getType()

  The type of the feature.

  Returns:
    the type of this sequence

### setType

    void setType(String type)
                 throws ChangeVetoException

  Change the type of this feature.

  Parameters:
    `type` - new type String
  Throws:
    `ChangeVetoException` - if the type can't be altered

### getTypeTerm

    Term getTypeTerm()

  An ontology term defining the type of feature. This is optional, and will default to `OntoTools.ANY` in implementations which aren't ontology aware.

  Since:
    1.4

### setTypeTerm

    void setTypeTerm(Term t)
                     throws ChangeVetoException,
                            InvalidTermException

  Set the type ontology-term for this feature. If this succeeds, it will generally also change the source name.

  Throws:
    `ChangeVetoException` - if changes are not allowed
    `InvalidTermException` - if the specified term is not an acceptable type for this feature.
  Since:
    1.4

### getSourceTerm

    Term getSourceTerm()

  An ontology term defining the source of this feature. This is optional, and will default to `OntoTools.ANY` in implementations which aren't ontology aware.

  Since:
    1.4

### setSourceTerm

    void setSourceTerm(Term t)
                       throws ChangeVetoException,
                              InvalidTermException

  Set the source ontology-term for this feature. If this succeeds, it will generally also change the source name.

  Throws:
    `ChangeVetoException` - if changes are not allowed
    `InvalidTermException` - if the specified term is not an acceptable type for this feature.
  Since:
    1.4

### getSource

    String getSource()

  The source of the feature. This may be a program or process.

  Returns:
    the source, or generator

### setSource

    void setSource(String source)
                   throws ChangeVetoException

  Change the source of the Feature.

  Parameters:
    `source` - the new source String
  Throws:
    `ChangeVetoException` - if the source can't be altered

### getSymbols

    SymbolList getSymbols()

  Return a list of symbols that are contained in this feature.

  The symbols may not be contiguous in the original sequence, but they will be concatenated together in the resulting SymbolList.

  The order of the Symbols within the resulting symbol list will be according to the concept of ordering within the location object.

  If the feature location is modified then this does not modify any SymbolList produced by earlier invocations of this method.

  Returns:
    a SymbolList containing each symbol of the parent sequence contained within this feature in the order they appear in the parent

### getParent

    FeatureHolder getParent()

  Return the `FeatureHolder` to which this feature has been attached. This will be a `Sequence` object for top level features, and a `Feature` object for features further down the tree.

### getSequence

    Sequence getSequence()

  Return the `Sequence` object to which this feature is (ultimately) attached. For top level features, this will be equal to the `FeatureHolder` returned by `getParent`.

  Returns:
    the ultimate parent Sequence

### features

    Iterator features()

  Iterate over any child features which are held by this feature. The order of iteration MAY be significant for some types of Feature.

  Specified by:
    `features` in interface `FeatureHolder`
  Returns:
    an Iterator

### makeTemplate

    Feature.Template makeTemplate()

  Create a new Template that could be used to generate a feature identical to this one. The fields of the template can be edited without changing the feature.

  Returns:
    a new Template that would make a feature like this one