package jsat.driftdetectors;
import java.io.Serializable;
import java.util.*;
/**
* Base class for providing common functionality to drift detection algorithms
* @author Edward Raff
*/
public abstract class BaseDriftDetector implements Cloneable, Serializable
{
private static final long serialVersionUID = -5857845807016446270L;
/**
* Tracks the number of updates / trial scene. May be reset as needed, so
* long as it increases compared to {@link #driftStart}
*/
protected int time = 0;
/**
* Controls the maximum amount of history to keep
*/
protected int maxHistory = Integer.MAX_VALUE;
/**
* Set to {@code true} to indicate that a warning mode in in effect.
*/
protected boolean warning = false;
/**
* Set to {@code true} to indicate that concept drift has occurred
*/
protected boolean drifting = false;
/**
* Set this value to the time point where the drift is believed to have
* started from. Set to -1 to indicate no drift
*/
protected int driftStart = -1;
/**
* Holds the associated object history. The history is always FIFO, with the
* end (tail) of the queue containing the most recent object, and the front
* (head) containing the oldest object.
*/
protected Deque history;
protected BaseDriftDetector()
{
}
/**
* Copy constructor
* @param toCopy the object to copy
*/
protected BaseDriftDetector(BaseDriftDetector toCopy)
{
this.time = toCopy.time;
this.maxHistory = toCopy.maxHistory;
this.warning = toCopy.warning;
this.driftStart = toCopy.driftStart;
if(toCopy.history != null)
{
this.history = new ArrayDeque(toCopy.history.size());
for(V v : toCopy.history)
this.history.add(v);
}
}
/**
* Returns {@code true} if the algorithm is in a warning state. This state
* indicates that the algorithm believes concept drift may be occurring, but
* is not confident enough to say that is had definitely occurred.
* Not all algorithms will raise a warning state, and some may only begin
* keeping track of history once in the warning state.
* @return {@code true} if concept drift may have started, but is not sure
*/
public boolean isWarning()
{
return warning;
}
/**
* Returns {@code true} if the algorithm believes that drift has definitely
* occurred. At this
* @return
*/
public boolean isDrifting()
{
return drifting;
}
/**
* Returns the maximum number of items that will be kept in the history.
* @return the maximum number of items that will be kept in the history.
*/
public int getMaxHistory()
{
return maxHistory;
}
/**
* Sets the maximum number of items to store in history. Setting this to
* {@code 0} will keep the detector from ever storing history.
* The user can still keep their own independent history or checkpoints by
* using the {@link #isDrifting() } and {@link #isWarning() } methods.
*
* The history size may be changed at any time, but may result in the loss
* of history.
*
* @param maxHistory the new maximum history size of objects added
*/
public void setMaxHistory(int maxHistory)
{
this.maxHistory = maxHistory;
if(history != null)
if (this.maxHistory == 0)
history.clear();
else
while (history.size() > maxHistory)
history.removeFirst();
}
/**
* Adds the given item to the history, creating a new history holder if
* needed. This method handles the cases where the max history is zero,
* and when the history is full (dropping the oldest)
* @param obj the object to add to the history
*/
protected void addToHistory(V obj)
{
if(maxHistory < 1)
return;
if(history == null)
if (maxHistory != Integer.MAX_VALUE)//we probably set it to a reasonable value
{
try
{
history = new ArrayDeque(maxHistory);
}
catch (Exception ex)
{
//what is we cause one of the many OOM exceptiosn b/c initial history was too big?
//AKA we googed on being helpful
history = new ArrayDeque();
}
}
else
history = new ArrayDeque();
if(history.size() == maxHistory)//make room
history.removeFirst();
history.add(obj);
}
/**
* Clears the current history
*/
public void clearHistory()
{
if(history != null)
history.clear();
}
/**
* Returns the number of items in recent history that differed from the
* historical values, or {@code -1} if there has not been any detected
* drift. This method will return {@code -1} even if {@link #isWarning() }
* is {@code true}.
* @return the number of updates ago that the drift started, or {@code -1}
* if no drift has occurred
*/
public int getDriftAge()
{
if(driftStart == -1)
return -1;
return time-driftStart;
}
/**
* Returns a new list containing up to {@link #getMaxHistory() } objects in
* the history that drifted away from the prior state of the model.
* The 0 index in the list will be the most recently added item, and the
* largest index will be the oldest item.
* @return the list of objects that make up the effected history
*/
public List getDriftedHistory()
{
int historyToGram = Math.min(time - driftStart, history.size());
ArrayList histList = new ArrayList(historyToGram);
Iterator histIter = history.descendingIterator();
while(histIter.hasNext() && historyToGram > 0)
{
historyToGram--;
histList.add(histIter.next());
}
return histList;
}
/**
* Adds a new point to the drift detector. If an escalation in state occurs,
* {@code true} will be returned. A change of state could be either drift
* occurring {@link #isDrifting} or a warning state {@link #isWarning}.
* If the detector was in a warning state and then goes back to normal,
* {@code false} will be returned.
*
* For binary (true / false) drift detectors, {@code value} will be
* considered {@code false} if and only if its value is equal to zero. Any
* non zero value will be treated as {@code true}
*
* Objects added with the value may or may not be added to the history, the
* behavior is algorithm dependent. Some may always add it to the history,
* while others will only begin collecting history once a warning state
* occurs.
*
* @param value the numeric value to add to the drift detector
* @param obj the object associated with this value. It may or may not be
* stored in the detectors history
* @return {@code true} if a drift has or may be starting.
* @throws UnhandledDriftException if {@link #driftHandled() } is not called
* after drifting is detected
*/
public abstract boolean addSample(double value, V obj);
/**
* This method should be called once the drift is handled. Once done, this
* method will clear the flags and prepare the detector to continue tracking
* drift again.
* By using this method, one can continue to track multiple future drift
* changes without having to feed the history data (which may be incomplete)
* into a new detector object.
*/
public void driftHandled()
{
warning = drifting = false;
driftStart = -1;
}
@Override
abstract public Object clone();
}
Ads help maintain this website.