import jalview.datamodel.SequenceFeature;
import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Comparator;
import java.util.List;
+import intervalstore.nonc.IntervalStore;
+
/**
* An adaption of FeatureStore that is efficient and lightweight, accelerating
* processing speed in JavaScript.
*
+ * It could be used in Java as well, with significant acceleration, but all this
+ * is so fast anyway that it probably will not be noticed in Java to speed it up
+ * by a factor of two or three. So for now, at least, this implementation is
+ * just in JavaScript. The flag for this is in SequenceFeatures.
+ *
+ * This implementation uses the IntervalStore developed by Bob Hanson, found at
+ * https://github.com/BobHanson/IntervalStoreJ, forked from the one developed by
+ * Mungo Carstairs at https://github.com/bartongroup/IntervalStoreJ.
+ *
+ * See the discussion folder at https://github.com/BobHanson/IntervalStoreJ for
+ * details.
+ *
* @author gmcarstairs
- * @author Bob Hanson 2019.08.03
+ * @author Bob Hanson 2019.08.03-2019.08.16
*
*/
public class FeatureStoreJS extends FeatureStore
{
- boolean contactsTainted = true;
+ private IntervalStore<SequenceFeature> featureStore;
- /**
- * Constructor
- */
public FeatureStoreJS()
{
- features = new ArrayList<>();
+ // the only reference to features field in this class -- for the superclass
+
+ // linked-list no-NCList IntervalStore with presort
+
+ features = featureStore = new IntervalStore<>(true);
}
/**
- * Returns a (possibly empty) list of features whose extent overlaps the given
- * range. The returned list is not ordered. Contact features are included if
- * either of the contact points lies within the range.
+ * Add a contact feature to the lists that hold them ordered by start (first
+ * contact) and by end (second contact) position, ensuring the lists remain
+ * ordered. This method allows duplicate features to be added, so test before
+ * calling to avoid this.
*
- * @param start
- * start position of overlap range (inclusive)
- * @param end
- * end position of overlap range (inclusive)
- * @return
+ * @param feature
+ * @return true
*/
-
@Override
- public List<SequenceFeature> findOverlappingFeatures(long start, long end,
- List<SequenceFeature> result)
+ protected synchronized boolean addContactFeature(SequenceFeature feature)
{
- if (result == null)
+ if (contactFeatureStarts == null)
{
- result = new ArrayList<>();
+ contactFeatureStarts = new ArrayList<>();
+ contactFeatureEnds = new ArrayList<>();
}
- if (contactFeatureStarts != null)
- {
- if (start == end)
- {
- findContactPoints(contactFeatureStarts, start, result, true);
- findContactPoints(contactFeatureEnds, start, result, false);
- }
- else
- {
- findContactFeatures(start, end, result);
- }
- }
- if (features.size() > 0)
- {
- findOverlaps(start, end, result);
- }
- return result;
+ contactFeatureStarts.add(
+ findFirstBegin(contactFeatureStarts, feature.begin), feature);
+ contactFeatureEnds.add(findFirstEnd(contactFeatureEnds, feature.end),
+ feature);
+ return true;
}
- // The following methods use a linked list of containment in SequenceFeature
- // rather than IntervalStore.
- //
- // There are two parts --- initialization, and overlap searching.
- //
- // Initialization involves two steps:
- //
- // (1) sorting of features by start position using a standard Array.sort with
- // Comparator.
- // (2) linking of features, effectively nesting them.
- //
- // Searching involves three steps:
- //
- // (1) binary search for a starting point within the sorted features array.
- // (2) traverse the linked lists with an end check to read out the
- // overlapped features at this position.
- // (3) For an interval, find the last feature that starts in this interval,
- // and add all features up through that feature.
- //
- // All of this is done with very simple standard methods.
-
- // Initialization
-
- /*
- * contact features ordered by first contact position
- */
- private SequenceFeature[] orderedFeatureStarts;
-
- private void rebuildArrays(int n)
- {
- if (startComp == null)
- {
- startComp = new StartComparator();
- }
- orderedFeatureStarts = new SequenceFeature[n];
- for (int i = n; --i >= 0;)
- {
- SequenceFeature sf = ((ArrayList<SequenceFeature>) features).get(i);
- sf.index = i; // for debugging only
- orderedFeatureStarts[i] = sf;
- }
- Arrays.sort(orderedFeatureStarts, startComp);
- linkFeatures(orderedFeatureStarts);
- }
/**
- * just a standard Comparator
+ * Add a feature to the IntervalStore, not allowing for duplicates.
+ *
+ *
+ * @return false if could not add it (late check for duplicate)
*/
- private static StartComparator startComp;
-
- class StartComparator implements Comparator<SequenceFeature>
+ @Override
+ protected synchronized boolean addPositionalFeature(
+ SequenceFeature feature)
{
-
- @Override
- public int compare(SequenceFeature o1, SequenceFeature o2)
- {
- int p1 = o1.begin;
- int p2 = o2.begin;
- return (p1 < p2 ? -1 : p1 > p2 ? 1 : 0);
- }
-
+ return featureStore.add(feature, false);
}
/**
- * Run through the sorted sequence array once, building the containedBy linked
- * list references. Does a check first to make sure there is actually
- * something out there that is overlapping. A null for sf.containedBy means
- * there are no overlaps for this feature.
+ * Initial check in FeatureStore.add(feature) that in other implementations
+ * does a containment check, but in this implementation just returns false to
+ * indicate that we should continue. This implementation will do this check as
+ * part of the add() method for greater efficiency (one binary search instead
+ * of two).
*
- * @param intervals
+ * @return false -- meaning "maybe not contained; continue adding"
*/
- private void linkFeatures(SequenceFeature[] intervals)
+ @Override
+ protected boolean checkContainsPositionalFeatureForAdd(
+ SequenceFeature feature)
{
- if (intervals.length < 2)
- {
- return;
- }
- int maxEnd = intervals[0].end;
- for (int i = 1, n = intervals.length; i < n; i++)
- {
- SequenceFeature sf = intervals[i];
- if (sf.begin <= maxEnd)
- {
- sf.containedBy = getContainedBy(intervals[i - 1], sf);
- }
- if (sf.end > maxEnd)
- {
- maxEnd = sf.end;
- }
- }
+ return false;
}
/**
- * Since we are traversing the sorted feature array in a forward direction,
- * all elements prior to the one we are working on have been fully linked. All
- * we are doing is following those links until we find the first array feature
- * with a containedBy element that has an end >= our begin point. It is
- * generally a very short list -- maybe one or two depths. But it might be
- * more than that.
+ * Check to see if a feature (or its equivalent based on
+ * IntervalI.equalsInterval) is already in this store. This method should be
+ * avoided except when necessary, as it involves a binary search with identity
+ * check.
*
- * @param sf
- * @param sf0
- * @return
+ * @return true if this feature or its equivalent (based on equalsInterval) is
+ * present already in the collection.
*/
- private SequenceFeature getContainedBy(SequenceFeature sf,
- SequenceFeature sf0)
+ @Override
+ protected boolean containsFeature(SequenceFeature feature)
{
- int begin = sf0.begin;
- while (sf != null)
- {
- if (begin <= sf.end)
- {
- // System.out.println("\nFS found " + sf0.index + ":" + sf0
- // + "\nFS in " + sf.index + ":" + sf);
- return sf;
- }
- sf = sf.containedBy;
- }
- return null;
+ return featureStore.contains(feature);
}
- // search-stage methods
+ @Override
+ protected boolean findAndRemoveNonContactFeature(SequenceFeature sf)
+ {
+ return featureStore.remove(sf);
+ }
/**
- * Binary search for contact start or end at a given (Overview) position.
+ * Add contact features to the result list where either the second or the
+ * first contact position lies within the target range, inclusively.
*
- * @param l
- * @param pos
+ * @param from
+ * @param to
* @param result
- * @param isStart
- *
- * @author Bob Hanson 2019.07.30
*/
- private static void findContactPoints(List<SequenceFeature> l, long pos,
- List<SequenceFeature> result, boolean isStart)
+ @Override
+ protected void findContactFeatures(long from, long to,
+ List<SequenceFeature> result)
{
- int low = 0;
- int high = l.size() - 1;
- while (low <= high)
- {
- int mid = (low + high) >>> 1;
- SequenceFeature f = l.get(mid);
- switch (Long.signum((isStart ? f.begin : f.end) - pos))
- {
- case -1:
- low = mid + 1;
- continue;
- case 1:
- high = mid - 1;
- continue;
- case 0:
- int m = mid;
- result.add(f);
- // could be "5" in 12345556788 ?
- while (++mid <= high && (f = l.get(mid)) != null
- && (isStart ? f.begin : f.end) == pos)
- {
- result.add(f);
- }
- while (--m >= low && (f = l.get(m)) != null
- && (isStart ? f.begin : f.end) == pos)
- {
- result.add(f);
- }
- return;
- }
- }
+ getContactStartOverlaps(from, to, result);
+ getContactEndOverlaps(from, to, result);
}
/**
- * Find all overlaps; special case when there is only one feature. The
- * required array of start-sorted SequenceFeature is created lazily.
+ * Locate the first feature start in a standard ArrayList that is at or after
+ * this position.
*
- * @param features
- * @param pos
- * @param result
*/
- private void findOverlaps(long start, long end,
- List<SequenceFeature> result)
+
+ @Override
+ protected int findFirstBegin(List<SequenceFeature> list, long pos)
{
- int n = features.size();
- switch (n)
+ int matched = list.size();
+ int end = matched - 1;
+ int start = (end < 0 || list.get(end).begin < pos ? matched : 0);
+ while (start <= end)
{
- case 0:
- return;
- case 1:
- checkOne(((ArrayList<SequenceFeature>) features).get(0), start, end,
- result);
- return;
- default:
- if (orderedFeatureStarts == null)
+ int mid = (start + end) / 2;
+ if (list.get(mid).begin >= pos)
{
- rebuildArrays(n);
+ matched = mid;
+ end = mid - 1;
}
- break;
- }
-
- // (1) Find the closest feature to this position.
-
- int index = findClosestFeature(orderedFeatureStarts, start);
- SequenceFeature sf = (index < 0 ? null : orderedFeatureStarts[index]);
-
- // (2) Traverse the containedBy field, checking for overlap.
-
- while (sf != null)
- {
- if (sf.end >= start)
+ else
{
- result.add(sf);
+ start = mid + 1;
}
- sf = sf.containedBy;
}
+ return matched;
+ }
- // (3) For an interval, find the last feature that starts in this interval,
- // and add all features up through that feature.
+ /**
+ * Locate the feature end in a standard ArrayList that is after or at this
+ * position.
+ *
+ */
- if (end > start)
+ @Override
+ protected int findFirstEnd(List<SequenceFeature> list, long pos)
+ {
+ int matched = list.size();
+ int end = matched - 1;
+ int start = 0;
+ while (start <= end)
{
- // fill in with all features that start within this interval, fully
- // inclusive
- int index2 = findClosestFeature(orderedFeatureStarts, end);
- while (++index <= index2)
+ int mid = (start + end) / 2;
+ if (list.get(mid).end >= pos)
{
- result.add(orderedFeatureStarts[index]);
+ matched = mid;
+ end = mid - 1;
+ }
+ else
+ {
+ start = mid + 1;
}
-
}
+ return matched;
}
/**
- * Quick check when we only have one feature.
+ * Returns a (possibly empty) list of features whose extent overlaps the given
+ * range. The returned list is ordered as follows:
+ *
+ * (1) ContactFeature starts
+ *
+ * (2) ContactFeature ends (that are not also starts)
+ *
+ * (3) noncontact SequenceFeatures, in reverse start order
+ *
+ * (This last reverse order is for efficiency in processing only.)
+ *
+ *
*
- * @param sf
* @param start
+ * start position of overlap range (inclusive)
* @param end
+ * end position of overlap range (inclusive)
+ *
* @param result
+ * optional result list; for highest efficiency, provide this
+ * parameter
+ * @return result same as result parameter, or a new ArrayList if that is null
*/
- private void checkOne(SequenceFeature sf, long start, long end,
+
+ @Override
+ public List<SequenceFeature> findOverlappingFeatures(long start, long end,
List<SequenceFeature> result)
{
- if (sf.begin <= end && sf.end >= start)
+ if (result == null)
{
- result.add(sf);
+ result = new ArrayList<>();
}
- return;
- }
-
- /**
- * A binary search identical to the one used for contact start/end, but here
- * we return the feature itself. Unlike Collection.BinarySearch, all we have
- * to be is close, not exact, and we make sure if there is a string of
- * identical starts, then we slide to the end so that we can check all of
- * them.
- *
- * @param l
- * @param pos
- * @return
- */
- private int findClosestFeature(SequenceFeature[] l, long pos)
- {
- int low = 0;
- int high = l.length - 1;
- while (low <= high)
+ if (contactFeatureStarts != null)
{
- int mid = (low + high) >>> 1;
- SequenceFeature f = l[mid];
- switch (Long.signum(f.begin - pos))
+ if (start == end)
{
- case -1:
- low = mid + 1;
- continue;
- case 1:
- high = mid - 1;
- continue;
- case 0:
-
- while (++mid <= high && l[mid].begin == pos)
- {
- ;
- }
- return --mid;
+ getContactPoints(contactFeatureStarts, start, result, true);
+ getContactPoints(contactFeatureEnds, start, result, false);
+ }
+ else
+ {
+ findContactFeatures(start, end, result);
}
}
- return (high < 0 ? -1 : high);
- }
-
- /**
- * Adds contact features to the result list where either the second or the
- * first contact position lies within the target range
- *
- * @param from
- * @param to
- * @param result
- */
- @Override
- protected void findContactFeatures(long from, long to,
- List<SequenceFeature> result)
- {
- findContactStartOverlaps(from, to, result);
- findContactEndOverlaps(from, to, result);
+ if (featureStore.size() > 0)
+ {
+ featureStore.findOverlaps(start, end, result);
+ }
+ return result;
}
/**
- * Adds to the result list any contact features whose end (second contact
- * point), but not start (first contact point), lies in the query from-to
- * range
+ * Adds to the result list any contact features having end (second contact
+ * point), but not start (first contact point), in the query from-to range
*
* @param from
* @param to
* @param result
*/
- private void findContactEndOverlaps(long from, long to,
+ private void getContactEndOverlaps(long from, long to,
List<SequenceFeature> result)
{
// find the first contact feature (if any)
}
/**
+ * Binary search for contact start or end matching a specific position. This
+ * efficient search was designed specifically for rapid return for the
+ * OverviewPanel. It's implementation sped processing of that panel by 2300%.
+ *
+ * @param l
+ * @param pos
+ * @param result
+ * @param isStart
+ *
+ * @author Bob Hanson 2019.07.30
+ */
+ private void getContactPoints(List<SequenceFeature> l, long pos,
+ List<SequenceFeature> result, boolean isStart)
+ {
+ int low = 0;
+ int high = l.size() - 1;
+ while (low <= high)
+ {
+ int mid = (low + high) >>> 1;
+ SequenceFeature f = l.get(mid);
+ switch (Long.signum((isStart ? f.begin : f.end) - pos))
+ {
+ case -1:
+ low = mid + 1;
+ continue;
+ case 1:
+ high = mid - 1;
+ continue;
+ case 0:
+ int m = mid;
+ result.add(f);
+ // could be "5" in 12345556788 ?
+ while (++mid <= high && (f = l.get(mid)) != null
+ && (isStart ? f.begin : f.end) == pos)
+ {
+ result.add(f);
+ }
+ while (--m >= low && (f = l.get(m)) != null
+ && (isStart ? f.begin : f.end) == pos)
+ {
+ result.add(f);
+ }
+ return;
+ }
+ }
+ }
+
+ /**
* Adds contact features whose start position lies in the from-to range to the
* result list
*
* @param result
*/
- private void findContactStartOverlaps(long from, long to,
+ private void getContactStartOverlaps(long from, long to,
List<SequenceFeature> result)
{
for (int i = findFirstBegin(contactFeatureStarts,
result.add(sf);
}
}
-
- public static int findFirstBegin(List<SequenceFeature> list, long pos)
- {
- int start = 0;
- int end = list.size() - 1;
- int matched = list.size();
-
- while (start <= end)
- {
- int mid = (start + end) / 2;
- if (list.get(mid).begin >= pos)
- {
- matched = mid;
- end = mid - 1;
- }
- else
- {
- start = mid + 1;
- }
- }
- return matched;
- }
-
- public static int findFirstEnd(List<SequenceFeature> list, long pos)
- {
- int start = 0;
- int end = list.size() - 1;
- int matched = list.size();
-
- while (start <= end)
- {
- int mid = (start + end) / 2;
- if (list.get(mid).end >= pos)
- {
- matched = mid;
- end = mid - 1;
- }
- else
- {
- start = mid + 1;
- }
- }
- return matched;
- }
-
-
}