FilterUtils (biojava-legacy 1.9.1 API)

java.lang.Object
- org.biojava.bio.seq.FilterUtils

```
public class FilterUtils
extends Object
```
A set of FeatureFilter algebraic operations.

Since:

1.2

Author:

Matthew Pocock, Thomas Down

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`FilterUtils.DelegatingTransformer` An implementation of FilterTransformer that attempts to transform by one transformer, and if that fails, by another.
`static interface`	`FilterUtils.FilterTransformer` An object able to transform some FeatureFilter instances sytematically into others.

Method Summary

Methods
Modifier and Type	Method and Description
`static FeatureFilter`	`all()` Return a filter which matches all features.
`static FeatureFilter`	`and(FeatureFilter[] filters)` Constructs a new filter which matches the intersection of a set of filters.
`static FeatureFilter`	`and(FeatureFilter c1, FeatureFilter c2)` Construct a new filter which matches the intersection of two other filters.
`static boolean`	`areDisjoint(FeatureFilter a, FeatureFilter b)` Determines if two queries can be proven to be disjoint.
`static boolean`	`areEqual(FeatureFilter f1, FeatureFilter f2)` Decide if two feature filters accept exactly the same set of features.
`static boolean`	`areProperSubset(FeatureFilter sub, FeatureFilter sup)` Determines if the set of features matched by sub can be `proven` to be a proper subset of the features matched by sup.
`static FeatureFilter`	`byAncestor(FeatureFilter ancestorFilter)` Match features where at least one of the ancestors matches the specified filter.
`static FeatureFilter`	`byAnnotation(Object key, Object value)` Match features where the annotation property named `key` is equal to `value`.
`static FeatureFilter`	`byAnnotationType(AnnotationType type)` Match features with annotations matching the specified `AnnotationType`
`static FeatureFilter`	`byAnnotationType(Object key, Class valClass)` Match features where the annotation property named `key` is an instance of `valClass`.
`static FeatureFilter`	`byChild(FeatureFilter childFilter)` Match features where at least one child feature matches the supplied filter.
`static FeatureFilter`	`byClass(Class clazz)` Construct a filter which matches features which are assignable to the specified class or interface.
`static FeatureFilter`	`byComponentName(String compName)` Construct a filter which matches all features which implement the `ComponentFeature` interface and have a `componentName` property equal to the specified value
`static FeatureFilter`	`byDescendant(FeatureFilter descFilter)` Match features where at least one decendant feature -- possibly but not necessarily an immediate child -- matches the specified filter.
`static FeatureFilter`	`byFrame(FramedFeature.ReadingFrame frame)` Construct a filter which matches FramedFeatures with the specified reading frame.
`static FeatureFilter`	`byPairwiseScore(double minScore, double maxScore)` Match SeqSimilaritiy features with scores in the specified range.
`static FeatureFilter`	`byParent(FeatureFilter parentFilter)` Match features where the parent feature matches the specified filter.
`static FeatureFilter`	`bySequenceName(String name)` Match features attached to sequences with a specified name.
`static FeatureFilter`	`bySource(String source)` Construct a filter which matches features with a specific `source` value.
`static FeatureFilter`	`byStrand(StrandedFeature.Strand strand)` Match StrandedFeatures on the specified strand.
`static FeatureFilter`	`byType(String type)` Construct a filter which matches features with a specific `type` value.
`static FeatureFilter`	`containedByLocation(Location loc)` Construct a filter which matches features with locations wholly contained by the specified `Location`.
`static Location`	`extractOverlappingLocation(FeatureFilter ff)` Try to determine the minimal location which all features matching a given filter must overlap.
`static FeatureFilter`	`hasAnnotation(Object key)` Match features where the property `key` has been defined as having some value, regardless of the exact value.
`static FeatureFilter`	`leaf()` Return a filter which matches features with zero children.
`static FeatureFilter`	`none()` Return a filter which matches no features.
`static FeatureFilter`	`not(FeatureFilter filter)` Construct a new filter which is the negation of `filter`.
`static FeatureFilter`	`onlyChildren(FeatureFilter child)` Construct a filter which matches features whose children all match the specified filter.
`static FeatureFilter`	`onlyDescendants(FeatureFilter desc)` Construct a filter which matches features whose decendants all match the specified filter.
`static FeatureFilter`	`optimize(FeatureFilter filter)` Attempts to reduce a FeatureFilter to an equivalent FeatureFilter with fewer terms.
`static FeatureFilter`	`or(FeatureFilter[] filters)` Construct a new filter which matches the intersection of two filters.
`static FeatureFilter`	`or(FeatureFilter c1, FeatureFilter c2)` Construct a new filter which matches the union of two filters.
`static FeatureFilter`	`overlapsLocation(Location loc)` Construct a filter which matches features with locations contained by or overlapping the specified `Location`.
`static FeatureFilter`	`shadowContainedByLocation(Location loc)` Construct a filter which matches features with locations where the interval between the `min` and `max` positions are contained by the specified `Location`.
`static FeatureFilter`	`shadowOverlapsLocation(Location loc)` Construct a filter which matches features with locations where the interval between the `min` and `max` positions are contained by or overlap the specified `Location`.
`static FeatureFilter`	`topLevel()` Return a filter which matches all top-level features.
`static FeatureFilter`	`transformFilter(FeatureFilter ff, FilterUtils.FilterTransformer trans)` This is a general framework method for transforming one filter into another.
`static Object`	`visitFilter(FeatureFilter filter, Visitor visitor)` Applies a visitor to a filter, and returns the visitor's result or null.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - areProperSubset
```
public static boolean areProperSubset(FeatureFilter sub,
                      FeatureFilter sup)
```
    Determines if the set of features matched by sub can be proven to be a proper subset of the features matched by sup.
    If the filter sub matches only features that are matched by sup, then it is a proper subset. It is still a proper subset if it does not match every feature in sup, as long as no feature matches sub that is rejected by sup.
    
    Parameters:
    sub - the subset filter
    sup - the superset filter
    
    Returns:
    true if sub is a proper subset of sup
  - areDisjoint
```
public static boolean areDisjoint(FeatureFilter a,
                  FeatureFilter b)
```
    Determines if two queries can be proven to be disjoint.
    They are disjoint if there is no element that is matched by both filters - that is, they have an empty intersection. Order of arguments to this method is not significant.
    
    Parameters:
    a - the first FeatureFilter
    b - the second FeatureFilter
    
    Returns:
    true if they are proved to be disjoint, false otherwise
  - extractOverlappingLocation
```
public static Location extractOverlappingLocation(FeatureFilter ff)
```
    Try to determine the minimal location which all features matching a given filter must overlap.
    
    Parameters:
    ff - A feature filter
    
    Returns:
    the minimal location which any features matching ff must overlap, or null if no proof is possible (normally indicates that the filter has nothing to do with location).
    Since:
    
    1.2
  - areEqual
```
public static final boolean areEqual(FeatureFilter f1,
               FeatureFilter f2)
```
    Decide if two feature filters accept exactly the same set of features.
    Two feature filters are equal if it can be proven that f1.accept(feature) == f2.accept(feature) for all values of feature. If areEqual returns false, this may indicate that they accept clearly different sets of features. It may also, howerver, indicate that the method was unable to prove that they were equal.
    
    Note that given a finite set of features, f1 and f2 may match the same sub-set of those features even if they are not equal.
    
    Parameters:
    f1 - the first filter
    f2 - the second filter
    
    Returns:
    true if they can be proven to be equivalent
  - byType
```
public static final FeatureFilter byType(String type)
```
    Construct a filter which matches features with a specific type value.
  - bySource
```
public static final FeatureFilter bySource(String source)
```
    Construct a filter which matches features with a specific source value.
  - byClass
```
public static final FeatureFilter byClass(Class clazz)
                                   throws ClassCastException
```
    Construct a filter which matches features which are assignable to the specified class or interface.
    
    Throws:
    
    ClassCastException
  - containedByLocation
```
public static final FeatureFilter containedByLocation(Location loc)
```
    Construct a filter which matches features with locations wholly contained by the specified Location.
  - overlapsLocation
```
public static final FeatureFilter overlapsLocation(Location loc)
```
    Construct a filter which matches features with locations contained by or overlapping the specified Location.
  - shadowOverlapsLocation
```
public static final FeatureFilter shadowOverlapsLocation(Location loc)
```
    Construct a filter which matches features with locations where the interval between the min and max positions are contained by or overlap the specified Location.
  - shadowContainedByLocation
```
public static final FeatureFilter shadowContainedByLocation(Location loc)
```
    Construct a filter which matches features with locations where the interval between the min and max positions are contained by the specified Location.
  - bySequenceName
```
public static final FeatureFilter bySequenceName(String name)
```
    Match features attached to sequences with a specified name.
  - not
```
public static final FeatureFilter not(FeatureFilter filter)
```
    Construct a new filter which is the negation of filter.
  - and
```
public static final FeatureFilter and(FeatureFilter c1,
                FeatureFilter c2)
```
    Construct a new filter which matches the intersection of two other filters.
  - and
```
public static final FeatureFilter and(FeatureFilter[] filters)
```
    Constructs a new filter which matches the intersection of a set of filters.
  - or
```
public static final FeatureFilter or(FeatureFilter c1,
               FeatureFilter c2)
```
    Construct a new filter which matches the union of two filters.
  - or
```
public static final FeatureFilter or(FeatureFilter[] filters)
```
    Construct a new filter which matches the intersection of two filters.
  - byAnnotationType
```
public static final FeatureFilter byAnnotationType(AnnotationType type)
```
    Match features with annotations matching the specified AnnotationType
  - byAnnotation
```
public static final FeatureFilter byAnnotation(Object key,
                         Object value)
```
    Match features where the annotation property named key is equal to value.
  - byAnnotationType
```
public static final FeatureFilter byAnnotationType(Object key,
                             Class valClass)
```
    Match features where the annotation property named key is an instance of valClass.
  - hasAnnotation
```
public static final FeatureFilter hasAnnotation(Object key)
```
    Match features where the property key has been defined as having some value, regardless of the exact value.
  - byStrand
```
public static final FeatureFilter byStrand(StrandedFeature.Strand strand)
```
    Match StrandedFeatures on the specified strand.
  - byParent
```
public static final FeatureFilter byParent(FeatureFilter parentFilter)
```
    Match features where the parent feature matches the specified filter. This cannot match top-level features.
  - byAncestor
```
public static final FeatureFilter byAncestor(FeatureFilter ancestorFilter)
```
    Match features where at least one of the ancestors matches the specified filter. This cannot match top-level features.
  - byChild
```
public static final FeatureFilter byChild(FeatureFilter childFilter)
```
    Match features where at least one child feature matches the supplied filter. This does not match leafFeatures.
  - byDescendant
```
public static final FeatureFilter byDescendant(FeatureFilter descFilter)
```
    Match features where at least one decendant feature -- possibly but not necessarily an immediate child -- matches the specified filter.
  - onlyChildren
```
public static final FeatureFilter onlyChildren(FeatureFilter child)
```
    Construct a filter which matches features whose children all match the specified filter. This filter always matches leaf features.
  - onlyDescendants
```
public static final FeatureFilter onlyDescendants(FeatureFilter desc)
```
    Construct a filter which matches features whose decendants all match the specified filter. This filter always matches leaf features.
  - byFrame
```
public static final FeatureFilter byFrame(FramedFeature.ReadingFrame frame)
```
    Construct a filter which matches FramedFeatures with the specified reading frame.
  - byPairwiseScore
```
public static final FeatureFilter byPairwiseScore(double minScore,
                            double maxScore)
```
    Match SeqSimilaritiy features with scores in the specified range.
  - byComponentName
```
public static final FeatureFilter byComponentName(String compName)
```
    Construct a filter which matches all features which implement the ComponentFeature interface and have a componentName property equal to the specified value
  - topLevel
```
public static final FeatureFilter topLevel()
```
    Return a filter which matches all top-level features. These are features which are direct children of a Sequence rather than another Feature.
  - leaf
```
public static final FeatureFilter leaf()
```
    Return a filter which matches features with zero children.
  - all
```
public static final FeatureFilter all()
```
    Return a filter which matches all features.
  - none
```
public static final FeatureFilter none()
```
    Return a filter which matches no features.
  - optimize
```
public static final FeatureFilter optimize(FeatureFilter filter)
```
    Attempts to reduce a FeatureFilter to an equivalent FeatureFilter with fewer terms.
    This will attempt to push all leaf constraints as far from the root of the filter expression as possible, in an attept to prove an empty or universal set. It will then propogate these through the logical operators in an attempt to reduce the entire expression to the empty or universal set. If filters can be combined (for example, overlapping constraints), then this will happen on the way.
    
    The resulting filter is guaranteed to accept exactly the same set of\ features that is accepted by the argument. In particular, areEqual(filter, optimize(filter)) is always true.
    
    Parameters:
    filter - the FeatureFilter to optimize
    
    Returns:
    an optimized version
  - transformFilter
```
public static FeatureFilter transformFilter(FeatureFilter ff,
                            FilterUtils.FilterTransformer trans)
```
    This is a general framework method for transforming one filter into another. This method will handle the logical elements of a query (and, or, not) and delegate all the domain-specific munging to a FilterTransformer object.
    
    The transformer could flip strands and locations of elements of a filter, add or remove attributes required in annotations, or systematically alter feature types or sources.
    
    Parameters:
    ff - the FeatureFilter to transform
    trans - a FilterTransformer encapsulating rules about how to transform filters
  - visitFilter
```
public static Object visitFilter(FeatureFilter filter,
                 Visitor visitor)
                          throws BioException
```
    Applies a visitor to a filter, and returns the visitor's result or null.
    
    Parameters:
    filter - the filter to scan
    visitor - the visitor to scan with
    
    Returns:
    the result of the visitor or null
    
    Throws:
    
    BioException - if the required walker could not be created

Class FilterUtils

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

areProperSubset

areDisjoint

extractOverlappingLocation

areEqual

byType

bySource

byClass

containedByLocation

overlapsLocation

shadowOverlapsLocation

shadowContainedByLocation

bySequenceName

not

and

and

or

or

byAnnotationType

byAnnotation

byAnnotationType

hasAnnotation

byStrand

byParent

byAncestor

byChild

byDescendant

onlyChildren

onlyDescendants

byFrame

byPairwiseScore

byComponentName

topLevel

leaf

all

none

optimize

transformFilter

visitFilter