weka.filters.supervised.attribute

Class TSLagMaker

java.lang.Object

weka.filters.Filter

weka.filters.supervised.attribute.TSLagMaker

All Implemented Interfaces:

Serializable, weka.core.CapabilitiesHandler, weka.core.CapabilitiesIgnorer, weka.core.CommandlineRunnable, weka.core.OptionHandler, weka.core.RevisionHandler, weka.filters.SupervisedFilter

public class TSLagMaker
extends weka.filters.Filter
implements weka.filters.SupervisedFilter, Serializable

A class for creating lagged versions of target variable(s) for use in time series forecasting. Uses the TimeseriesTranslate filter. Has options for creating averages of consecutive lagged variables (which can be useful for long lagged variables). Some polynomials of time are also created (if there is a time stamp), such as time^2 and time^3. Also creates cross products between time and the lagged and averaged lagged variables. If there is no date time stamp in the data then the user has the option of having an artificial time stamp created. Time stamps, real or otherwise, are used for modeling trends rather than using a differencing-based approach. Also has routines for dealing with a date timestamp - i.e. it can detect a monthly time period (because months are different lengths) and maps date time stamps to equal spaced time intervals. For example, in general, a date time stamp is remapped by subtracting the first observed value and adding this value divided by the constant delta (difference between consecutive steps) to the result. In the case of a detected monthly time period, the remapping involves subtracting the base year and then adding to this the number of the month within the current year plus twelve times the number of intervening years since the base year. Also has routines for adding new attributes derived from a date time stamp to the data - e.g. AM indicator, day of the week, month, quarter etc. In the case where there is no real date time stamp, the user may specify a nominal periodic variable (if one exists in the data). For example, month might be coded as a nominal value. In this case it can be specified as the primary periodic variable. The point is, that in all these cases (nominal periodic and date-derived periodics), we are able to determine what the value of these variables will be in future instances (as computed from the last known historic instance).

Version:

$Revision: 52588 $

Author:

Mark Hall (mhall{[at]}pentaho{[dot]}com)

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TSLagMaker.Periodicity Enum defining periodicity
static class	TSLagMaker.PeriodicityHandler Helper class to manage time stamp manipulation with respect to various periodicities.

Constructor Summary

Constructors

Constructor and Description
TSLagMaker()

Method Summary

Methods

Modifier and Type	Method and Description
void	addCustomPeriodic(String customPeriodic) Add a custom date-derived periodic
double	advanceSuppliedTimeValue(double valueToAdvance) Utility method to advance a supplied time value by one unit according to the periodicity set for this LagMaker.
boolean	batchFinished()
void	clearCustomPeriodics() Clear all custom date-derived periodic fields.
void	clearLagHistories() Clears any history accumulated in the lag creating filters.
weka.core.Instances	createTimeLagCrossProducts(weka.core.Instances insts)
double	decrementSuppliedTimeValue(double valueToDecrement)
static TSLagMaker.PeriodicityHandler	determinePeriodicity(weka.core.Instances insts, String timeName, TSLagMaker.Periodicity userHint) Utility method that uses heuristics to identify the periodicity of the data with respect to a time stamp.
boolean	getAddAMIndicator() Return true if an AM indicator attribute is to be created.
boolean	getAddDayOfMonth() Return true if a day of the month attribute is to be created.
boolean	getAddDayOfWeek() Return true if a day of the week attribute is to be created.
boolean	getAddMonthOfYear() Returns true if a month of the year attribute is to be created.
boolean	getAddNumDaysInMonth() Return true if a num days in the month attribute is to be created.
boolean	getAddQuarterOfYear() Returns true if a quarter attribute is to be created.
boolean	getAddWeekendIndicator() Returns true if a weekend indicator attribute is to be created.
boolean	getAdjustForTrends() Returns true if we are adjusting for trends via a real or artificial time stamp.
boolean	getAdjustForVariance() Returns true if we are adjusting for variance by taking the log of the target(s).
double	getArtificialTimeStartValue() Returns the current value of the artificial time stamp.
boolean	getAverageConsecutiveLongLags() Returns true if consecutive long lagged variables are to be averaged.
int	getAverageLagsAfter() Return the point after which long lagged variables will be averaged.
weka.core.Capabilities	getCapabilities() Returns the Capabilities of this filter.
double	getCurrentTimeStampValue() Returns the current (i.e.
Map<String,ArrayList<CustomPeriodicTest>>	getCustomPeriodics() Get the date-derived custom periodic attributes in use.
double	getDeltaTime() Return the difference between time values.
List<String>	getFieldsToLag() Get the names of the fields to create lagged variables for.
String	getFieldsToLagAsString()
boolean	getIncludePowersOfTime() Get whether to include powers of time in the transformed data
boolean	getIncludeTimeLagProducts() Get whether to include products between time and the lagged variables
String	getLagRange() Get the ranges used to fine tune lag selection
int	getMaxLag() Get the maximum lag to create.
int	getMinLag() Get the minimum lag to create.
int	getNumConsecutiveLongLagsToAverage() Get the number of consecutive long lagged variables to average.
String[]	getOptions() Gets the current settings of the LagMaker.
List<String>	getOverlayFields() Get overlay fields
TSLagMaker.Periodicity	getPeriodicity() Gets the Periodicity representing the time stamp in use for this lag maker.
String	getPrimaryPeriodicFieldName() The name of the primary periodic attribute or null if one hasn't been specified.
boolean	getRemoveLeadingInstancesWithUnknownLagValues() Get whether to drop instances at the start of the transformed data where lag values are unknown/missing
String	getSkipEntries() Get a list of time units to be 'skipped' - i.e.
String	getTimeStampField() Get the name of the time stamp field.
weka.core.Instances	getTransformedData(weka.core.Instances insts) Creates a transformed data set based on the user's settings
String	globalInfo()
void	incrementArtificialTimeValue(int increment) Increment the artificial time value with the supplied incrememt value.
boolean	input(weka.core.Instance instance)
boolean	isUsingAnArtificialTimeIndex() Returns true if an artificial time index is in use.
Enumeration<weka.core.Option>	listOptions() Returns an enumeration describing the available options.
weka.core.Instance	processInstance(weka.core.Instance source, boolean incrementTime, boolean setAnyPeriodic)
weka.core.Instance	processInstance(weka.core.Instance source, boolean incrementTime, boolean setAnyPeriodic, boolean temporary) Process an instance in the original format and produce a transformed instance as output.
weka.core.Instance	processInstancePreview(weka.core.Instance source, boolean incrementTime, boolean setAnyPeriodic)
void	reset() Reset the lag maker.
void	setAddAMIndicator(boolean am) Set whether to create an AM indicator attribute.
void	setAddDayOfMonth(boolean d) Set whether to create a day of the month attribute.
void	setAddDayOfWeek(boolean d) Set whether to create a day of the week attribute.
void	setAddMonthOfYear(boolean m) Set whether to create a month of the year attribute.
void	setAddNumDaysInMonth(boolean d) Set whether to create a numeric attribute that holds the number of days in the month.
void	setAddQuarterOfYear(boolean q) Set whether to create a quarter attribute.
void	setAddWeekendIndicator(boolean w) Set whether to create a weekend indicator attribute.
void	setAdjustForTrends(boolean a) Set whether to adjust for trends or not.
void	setAdjustForVariance(boolean v) Set whether to adjust for variance in the data by taking the log of the target(s).
void	setArtificialTimeStartValue(double value) Set the starting value for the artificial time stamp.
void	setAverageConsecutiveLongLags(boolean avg) Sets whether to average consecutive long lagged variables.
void	setAverageLagsAfter(int a) Set at which point consecutive long lagged variables are to be averaged (default = 2, i.e.
void	setCustomPeriodics(Map<String,ArrayList<CustomPeriodicTest>> custom) Set the date-derived custom periodic fields to use/compute
void	setFieldsToLag(List<String> names) Set the names of the fields to create lagged variables for
void	setFieldsToLagAsString(String toLag)
void	setIncludePowersOfTime(boolean p) Set whether to include powers of time in the transformed data
void	setIncludeTimeLagProducts(boolean includeTimeLagProducts) Set whether to include products between time and the lagged variables
boolean	setInputFormat(weka.core.Instances instanceInfo)
void	setLagRange(String lagRange) Set ranges to fine tune lag selection.
void	setMaxLag(int max) Set the maximum lag to create (default = 12, i.e.
void	setMinLag(int min) Set the minimum lag to create (default = 1, i.e.
void	setNumConsecutiveLongLagsToAverage(int c) Set the number of long lagged variables to average for each averaged variable created (default = 2, e.g.
void	setOptions(String[] options) Parses a given list of options.
void	setOverlayFields(List<String> overlayNames) Set the names of fields in the data that are to be considered "overlay" fields - i.e.
void	setPeriodicity(TSLagMaker.Periodicity toUse) Set the periodicity for the data.
void	setPrimaryPeriodicFieldName(String p) Set the name of a periodic attribute in the data.
void	setRemoveLeadingInstancesWithUnknownLagValues(boolean b) Set whether to drop instances at the start of the transformed data where lag values are unknown/missing
void	setSkipEntries(String skipEntries) Set the list of time units to be 'skipped' - i.e.
void	setTimeStampField(String name) Set the name of the time stamp field in the data

Methods inherited from class weka.filters.Filter

batchFilterFile, debugTipText, doNotCheckCapabilitiesTipText, filterFile, getCapabilities, getCopyOfInputFormat, getDebug, getDoNotCheckCapabilities, getOutputFormat, getRevision, isFirstBatchDone, isNewBatch, isOutputFormatDefined, main, makeCopies, makeCopy, mayRemoveInstanceAfterFirstBatchDone, numPendingOutput, output, outputPeek, postExecution, preExecution, run, runFilter, setDebug, setDoNotCheckCapabilities, toString, useFilter, wekaStaticWrapper

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TSLagMaker

public TSLagMaker()

Method Detail

globalInfo

public String globalInfo()

determinePeriodicity

public static TSLagMaker.PeriodicityHandler determinePeriodicity(weka.core.Instances insts,
                                                 String timeName,
                                                 TSLagMaker.Periodicity userHint)

Utility method that uses heuristics to identify the periodicity of the data with respect to a time stamp. If the time stamp is not a date then the periodicity is UNKNOWN with a delta set by computing the average difference between consecutive time stamp values. Configures the periodicity with first and last time stamp entries in the data.

Parameters:

insts - the instances to determine the periodicity from

timeName - the name of the time stamp attribute

userHint - a specific periodicity to defer to. The user should provide a specific periodicity when the data has non-constant differences in time between consecutive elements and a skip list will be used to correct for this. Specifying UNKNOWN as the periodicity here will result in the heuristic detection routine being applied.

Returns:

the configured Periodicity of the data.

reset

public void reset()

Reset the lag maker.

listOptions

public Enumeration<weka.core.Option> listOptions()

Returns an enumeration describing the available options.

Specified by:

listOptions in interface weka.core.OptionHandler

Overrides:

listOptions in class weka.filters.Filter

Returns:

an enumeration of all the available options.

getOptions

public String[] getOptions()

Gets the current settings of the LagMaker.

Specified by:

getOptions in interface weka.core.OptionHandler

Overrides:

getOptions in class weka.filters.Filter

Returns:

an array of strings suitable for passing to setOptions

setOptions

public void setOptions(String[] options)
                throws Exception

Parses a given list of options.

Specified by:

setOptions in interface weka.core.OptionHandler

Overrides:

setOptions in class weka.filters.Filter

Parameters:

options - the list of options as an array of strings

Throws:

Exception - if an option is not supported

getCustomPeriodics

public Map<String,ArrayList<CustomPeriodicTest>> getCustomPeriodics()

Get the date-derived custom periodic attributes in use.

Returns:

a Map, keyed by field name, of custom date-derived periodic fields.

setCustomPeriodics

public void setCustomPeriodics(Map<String,ArrayList<CustomPeriodicTest>> custom)

Set the date-derived custom periodic fields to use/compute

Parameters:

custom - a Map, keyed by field name, of custom date-derived periodic fields to use.

addCustomPeriodic

public void addCustomPeriodic(String customPeriodic)

Add a custom date-derived periodic

Parameters:

customPeriodic - the new custom date-derived periodic in textual form.

clearCustomPeriodics

public void clearCustomPeriodics()

Clear all custom date-derived periodic fields.

getFieldsToLag

public List<String> getFieldsToLag()

Get the names of the fields to create lagged variables for.

Returns:

a List of field names for which lagged variables will be created.

setFieldsToLag

@ProgrammaticProperty
public void setFieldsToLag(List<String> names)
                    throws Exception

Set the names of the fields to create lagged variables for

Parameters:

names - a List of field names for which to create lagged variables

Throws:

Exception - if a problem occurs

setFieldsToLagAsString

@OptionMetadata(displayName="Fields to lag",
                description="1-based index ranges, or, comma-separated list of field names to lag",
                displayOrder=1)
public void setFieldsToLagAsString(String toLag)

getFieldsToLagAsString

public String getFieldsToLagAsString()

getOverlayFields

public List<String> getOverlayFields()

Get overlay fields

Returns:

a list of field names that are set as "overlay" fields

setOverlayFields

@ProgrammaticProperty
public void setOverlayFields(List<String> overlayNames)

Set the names of fields in the data that are to be considered "overlay" fields - i.e. they will be externally provided for future instances.

Parameters:

overlayNames - the names of the fields that are to be considered "overlay" fields

getTimeStampField

public String getTimeStampField()

Get the name of the time stamp field.

Returns:

the name of the time stamp field or null if one hasn't been specified.

setTimeStampField

@OptionMetadata(displayName="Timestamp field",
                description="Field (if any) to use as the timestamp",
                displayOrder=0)
public void setTimeStampField(String name)

Set the name of the time stamp field in the data

Parameters:

name - the name of the time stamp field

getRemoveLeadingInstancesWithUnknownLagValues

public boolean getRemoveLeadingInstancesWithUnknownLagValues()

Get whether to drop instances at the start of the transformed data where lag values are unknown/missing

Returns:

true if leading instances with unknown lag values are to be removed

setRemoveLeadingInstancesWithUnknownLagValues

@OptionMetadata(displayName="Remove instances with unknown lag values",
                description="Whether to remove leading training instances that contain unknown lag values (ie missing lag values)",
                displayOrder=7)
public void setRemoveLeadingInstancesWithUnknownLagValues(boolean b)

Set whether to drop instances at the start of the transformed data where lag values are unknown/missing

Parameters:

b - true if leading instances with unknown lag values are to be removed

getAdjustForTrends

public boolean getAdjustForTrends()

Returns true if we are adjusting for trends via a real or artificial time stamp.

Returns:

true if we are adjusting for trends via a real or artificial time stamp in the data.

setAdjustForTrends

@OptionMetadata(displayName="Adjust for trends",
                description="Whether to adjust for trends in the data by adding powers of time and time-lag cross-products. If there is no real timestamp in the data then an artificial one will be added.",
                displayOrder=17)
public void setAdjustForTrends(boolean a)

Set whether to adjust for trends or not. If there is no time stamp field specified, and this is set to true, then an artificial time stamp will be created.

Parameters:

a - true if we are to adjust for trends via a real or artificial time stamp

getIncludeTimeLagProducts

public boolean getIncludeTimeLagProducts()

Get whether to include products between time and the lagged variables

Returns:

true if the transformed data will include products of time and lagged variables

setIncludeTimeLagProducts

@OptionMetadata(displayName="Include products of time and lagged variables",
                description="Include time-lag crossproduct fields",
                displayOrder=19)
public void setIncludeTimeLagProducts(boolean includeTimeLagProducts)

Set whether to include products between time and the lagged variables

Parameters:

includeTimeLagProducts - true if the transformed data will include products of time and lagged variables

getIncludePowersOfTime

public boolean getIncludePowersOfTime()

Get whether to include powers of time in the transformed data

Returns:

true if the transformed data will include powers of time

setIncludePowersOfTime

@OptionMetadata(displayName="Include powers of time",
                description="Include fields containing powers of time (^2, ^3)",
                displayOrder=18)
public void setIncludePowersOfTime(boolean p)

Set whether to include powers of time in the transformed data

Parameters:

p - true if the transformed data will include powers of time

getAdjustForVariance

public boolean getAdjustForVariance()

Returns true if we are adjusting for variance by taking the log of the target(s).

Returns:

true if we are adjusting for variance.

setAdjustForVariance

@OptionMetadata(displayName="Adjust for variance in lagged variables",
                description="Adjust for variance in fields being lagged by taking the log",
                displayOrder=8)
public void setAdjustForVariance(boolean v)

Set whether to adjust for variance in the data by taking the log of the target(s).

Parameters:

v - true to adjust for variance by taking the log of the target(s).

getMinLag

public int getMinLag()

Get the minimum lag to create.

Returns:

the minimum lag to create.

setMinLag

@OptionMetadata(displayName="Minimum lag length",
                description="The minimum length of lag to create",
                displayOrder=2)
public void setMinLag(int min)

Set the minimum lag to create (default = 1, i.e. t-1).

Parameters:

min - the minimum lag to create

getMaxLag

public int getMaxLag()

Get the maximum lag to create.

Returns:

the maximum lag to create.

setMaxLag

@OptionMetadata(displayName="Maximum lag length",
                description="The maximum length of lag to create",
                displayOrder=3)
public void setMaxLag(int max)

Set the maximum lag to create (default = 12, i.e. t-12).

Parameters:

max - the maximum lag to create.

getLagRange

public String getLagRange()

Get the ranges used to fine tune lag selection

Returns:

the ranges (if any) used to fine tune lag selection

setLagRange

@OptionMetadata(displayName="Lag ranges",
                description="Optional ranges by which to tune lag selection (eg 2,3,4,7-9)",
                displayOrder=4)
public void setLagRange(String lagRange)

Set ranges to fine tune lag selection.

Parameters:

lagRange - a set of ranges (e.g. 2,3,4,7-9).

getAverageConsecutiveLongLags

public boolean getAverageConsecutiveLongLags()

Returns true if consecutive long lagged variables are to be averaged.

Returns:

true if consecutive long lagged variables are to be averaged.

setAverageConsecutiveLongLags

@OptionMetadata(displayName="Average long lags",
                description="Whether to average consecutive long lagged variables",
                displayOrder=5)
public void setAverageConsecutiveLongLags(boolean avg)

Sets whether to average consecutive long lagged variables. Setting this to true creates new variables that are averages of long lags and the original lagged variables involved are removed.

Parameters:

avg - true if consecutive long lags are to be averaged.

getAverageLagsAfter

public int getAverageLagsAfter()

Return the point after which long lagged variables will be averaged.

Returns:

the point after which long lagged variables will be averaged.

setAverageLagsAfter

@OptionMetadata(displayName="Average lags longer than t-x",
                description="Set at which point consecutive long lagged variables
are to be averaged (default = 2); only has an effect if averaging
of long lagged variables is turned on.",
                displayOrder=6)
public void setAverageLagsAfter(int a)

Set at which point consecutive long lagged variables are to be averaged (default = 2, i.e. start replacing lagged variables after t-2 with averages).

Parameters:

a - the point at which to start averaging consecutive long lagged variables.

getNumConsecutiveLongLagsToAverage

public int getNumConsecutiveLongLagsToAverage()

Get the number of consecutive long lagged variables to average.

Returns:

the number of long lagged variables to average.

setNumConsecutiveLongLagsToAverage

@OptionMetadata(displayName="Number of consecutive long lags to average",
                description="Set the number of long lagged variables to average for each averaged variable created (default = 2)",
                displayOrder=7)
public void setNumConsecutiveLongLagsToAverage(int c)

Set the number of long lagged variables to average for each averaged variable created (default = 2, e.g. a set average after value of 2 and a num consecutive to average = 2 will average t-3 and t-4 into a new variable, t-5 and t-6 into a new variable ect.

Parameters:

c - the number of consecutive long lagged variables to average.

getPrimaryPeriodicFieldName

public String getPrimaryPeriodicFieldName()

The name of the primary periodic attribute or null if one hasn't been specified.

Returns:

the name of the primary periodic attribute or null if one hasn't been specified.

setPrimaryPeriodicFieldName

@OptionMetadata(displayName="Primary periodic attribute",
                description="The name of the primary periodic attribute (if any); this attribute has to be nominal and cyclic",
                displayOrder=9)
public void setPrimaryPeriodicFieldName(String p)

Set the name of a periodic attribute in the data. This attribute has to be nominal and cyclic so that it is possible to know what the value will be given the current one.

Parameters:

p - the name of the primary periodic attribute (if any) in the data.

getAddAMIndicator

public boolean getAddAMIndicator()

Return true if an AM indicator attribute is to be created.

Returns:

true if an AM indiciator attribute is to be created.

setAddAMIndicator

@OptionMetadata(displayName="Add AM indicator",
                description="Add an indicator for AM to the data",
                displayOrder=10)
public void setAddAMIndicator(boolean am)

Set whether to create an AM indicator attribute. Has no effect if there isn't a date-based time stamp in the data.

Parameters:

am - true if an AM indicator attribute is to be created.

getAddDayOfWeek

public boolean getAddDayOfWeek()

Return true if a day of the week attribute is to be created.

Returns:

true if a day of the week attribute is to be created.

setAddDayOfWeek

@OptionMetadata(displayName="Add day of the week",
                description="Add a day of the week field to the data",
                displayOrder=11)
public void setAddDayOfWeek(boolean d)

Set whether to create a day of the week attribute. Has no effect if there isn't a date-based time stamp in the data.

Parameters:

d - true if a day of the week attribute is to be created.

getAddDayOfMonth

public boolean getAddDayOfMonth()

Return true if a day of the month attribute is to be created.

Returns:

true if a day of the month attribute is to be created.

setAddDayOfMonth

@OptionMetadata(displayName="Add day of the month",
                description="Add a day of the month field to the data",
                displayOrder=12)
public void setAddDayOfMonth(boolean d)

Set whether to create a day of the month attribute. Has no effect if there isn't a date-based time stamp in the data.

Parameters:

d - true if a day of the month attribute is to be created.

getAddNumDaysInMonth

public boolean getAddNumDaysInMonth()

Return true if a num days in the month attribute is to be created.

Returns:

true if a num days in the month attribute is to be created.

setAddNumDaysInMonth

@OptionMetadata(displayName="Add num days in month",
                description="Add a field that contains the number of days in the month",
                displayOrder=13)
public void setAddNumDaysInMonth(boolean d)

Set whether to create a numeric attribute that holds the number of days in the month.

Parameters:

d - true if a num days in month attribute is to be created.

getAddWeekendIndicator

public boolean getAddWeekendIndicator()

Returns true if a weekend indicator attribute is to be created.

Returns:

true if a weekend indicator attribute is to be created.

setAddWeekendIndicator

@OptionMetadata(displayName="Add weekend indicator",
                description="Add a weekend indicator to the data",
                displayOrder=14)
public void setAddWeekendIndicator(boolean w)

Set whether to create a weekend indicator attribute. Has no effect if there isn't a date-based time stamp in the data.

Parameters:

w - true if a weekend indicator attribute is to be created.

getAddMonthOfYear

public boolean getAddMonthOfYear()

Returns true if a month of the year attribute is to be created.

Returns:

true if a month of the year attribute is to be created.

setAddMonthOfYear

@OptionMetadata(displayName="Add month of the year",
                description="Add a month of the year field to the data",
                displayOrder=15)
public void setAddMonthOfYear(boolean m)

Set whether to create a month of the year attribute. Has no effect if there isn't a date-based time stamp in the data.

Parameters:

m - true if a month of the year attribute is to be created.

getAddQuarterOfYear

public boolean getAddQuarterOfYear()

Returns true if a quarter attribute is to be created.

Returns:

true if a quarter attribute is to be created.

setAddQuarterOfYear

@OptionMetadata(displayName="Add quarter of the year",
                description="Add a quarter of the year field to the data",
                displayOrder=16)
public void setAddQuarterOfYear(boolean q)

Set whether to create a quarter attribute. Has no effect if there isn't a date-based time stamp in the data.

Parameters:

q - true if a quarter attribute is to be added.

isUsingAnArtificialTimeIndex

public boolean isUsingAnArtificialTimeIndex()

Returns true if an artificial time index is in use.

Returns:

true if an artificial time index is in use.

getArtificialTimeStartValue

public double getArtificialTimeStartValue()
                                   throws Exception

Returns the current value of the artificial time stamp. After training, after priming, and prior to forecasting, this will be equal to the number of training instances seen.

Returns:

the current value of the artificial time stamp.

Throws:

Exception - if an artificial time stamp is not being used.

setArtificialTimeStartValue

@ProgrammaticProperty
public void setArtificialTimeStartValue(double value)
                                 throws Exception

Set the starting value for the artificial time stamp.

Parameters:

value - the value to initialize the artificial time stamp with.

Throws:

Exception - if an artificial time stamp is not being used.

getCurrentTimeStampValue

public double getCurrentTimeStampValue()
                                throws Exception

Returns the current (i.e. most recent) time stamp value. Unlike an artificial time stamp, the value after training, after priming and before forecasting, will be equal to the time stamp of the most recent priming instance.

Returns:

the current time stamp value

Throws:

Exception - if the lag maker is not adjusting for trends or no time stamp attribute has been specified.

incrementArtificialTimeValue

public void incrementArtificialTimeValue(int increment)

Increment the artificial time value with the supplied incrememt value.

Parameters:

increment - the value to increment by.

getDeltaTime

public double getDeltaTime()

Return the difference between time values. This may be only approximate for periods based on dates. It is best to used date-based arithmetic in this case for incrementing/decrementing time stamps.

Returns:

the (average) difference between time values.

getPeriodicity

public TSLagMaker.Periodicity getPeriodicity()

Gets the Periodicity representing the time stamp in use for this lag maker. If the lag maker is not adjusting for trends, or an artificial time stamp is being used, then null is returned.

Returns:

the Periodicity in use, or null if the lag maker is not adjusting for trends or is using an artificial time stamp.

setPeriodicity

@OptionMetadata(displayName="Periodicity of the data",
                description="User hint for the periodicity of the data (ignored when using an artificial time stamp or not adjusting for trends); heuristics are used when set to UNKNOWN",
                displayOrder=8)
public void setPeriodicity(TSLagMaker.Periodicity toUse)

Set the periodicity for the data. This is ignored if the lag maker is not adjusting for trends or is using an artificial time stamp. If not specified or set to Periodicity.UNKNOWN (the default) then heuristics will be used to try and automatically determine the periodicity.

Parameters:

toUse - the periodicity to use

getSkipEntries

public String getSkipEntries()

Get a list of time units to be 'skipped' - i.e. not considered as an increment. E.g financial markets don't trade on the weekend, so the difference between friday closing and the following monday closing is one time unit (and not three). Can accept strings such as "sat", "sunday", "jan", "august", or explicit dates (with optional formatting string) such as "2011-07-04@yyyy-MM-dd", or integers. Integers are interpreted with respect to the periodicity - e.g for daily data they are interpreted as day of the year; for hourly data, hour of the day; weekly data, week of the year.

Returns:

a comma-separated list of strings, explicit dates and integers

setSkipEntries

@OptionMetadata(displayName="Set timestamp skip list",
                description="Set the list of time units to be \'skipped\' - ie not considered as an increment. E.g. financial markets don\'t trade on the weekend, so the difference between friday closing and the following monday closing is one time unit (and not three). Can accept strings such as \'sat\', \'sunday\', \'jan\', \'august\', or explicit dates (with optional formatting string) such as \'2011-07-04@yyyy-MM-dd\', or integers. Integers are interpretted with respect to the periodicity - e.g. for daily data they are interpreted as the day of the year; for hourly data, hour of the day etc.",
                displayOrder=20)
public void setSkipEntries(String skipEntries)

Set the list of time units to be 'skipped' - i.e. not considered as an increment. E.g financial markets don't trade on the weekend, so the difference between friday closing and the following monday closing is one time unit (and not three). Can accept strings such as "sat", "sunday", "jan", "august", or explicit dates (with optional formatting string) such as "2011-07-04@yyyy-MM-dd", or integers. Integers are interpreted with respect to the periodicity - e.g for daily data they are interpreted as day of the year; for hourly data, hour of the day; weekly data, week of the year.

Parameters:

skipEntries - a comma separated list of strings, explicit dates and integers.

createTimeLagCrossProducts

public weka.core.Instances createTimeLagCrossProducts(weka.core.Instances insts)
                                               throws Exception

Throws:

Exception

getTransformedData

public weka.core.Instances getTransformedData(weka.core.Instances insts)
                                       throws Exception

Creates a transformed data set based on the user's settings

Parameters:

insts - the instances to transform

Returns:

a transformed data set

Throws:

Exception - if a problem occurs during the creation of lagged and auxiliary attributes.

processInstance

public weka.core.Instance processInstance(weka.core.Instance source,
                                 boolean incrementTime,
                                 boolean setAnyPeriodic)
                                   throws Exception

Throws:

Exception

processInstancePreview

public weka.core.Instance processInstancePreview(weka.core.Instance source,
                                        boolean incrementTime,
                                        boolean setAnyPeriodic)
                                          throws Exception

Throws:

Exception

processInstance

public weka.core.Instance processInstance(weka.core.Instance source,
                                 boolean incrementTime,
                                 boolean setAnyPeriodic,
                                 boolean temporary)
                                   throws Exception

Process an instance in the original format and produce a transformed instance as output. Assumes that the lag maker has been configured an initialized with a call to getTransformedDataset()

Parameters:

source - an instance in original format

incrementTime - true if any time stamp value should be incremented based on the time stamp value from the last instance seen and set in the outputted instance

setAnyPeriodic - true if any user-specified periodic value should be set in the transformed instance based on the value from the last instance seen.

Returns:

a transformed instance

Throws:

Exception - if something goes wrong.

clearLagHistories

public void clearLagHistories()
                       throws Exception

Clears any history accumulated in the lag creating filters.

Throws:

Exception - if something goes wrong.

advanceSuppliedTimeValue

public double advanceSuppliedTimeValue(double valueToAdvance)

Utility method to advance a supplied time value by one unit according to the periodicity set for this LagMaker.

Parameters:

valueToAdvance - the time value to advance

Returns:

the advanced value or the original value if this lag maker is not adjusting for trends

decrementSuppliedTimeValue

public double decrementSuppliedTimeValue(double valueToDecrement)

getCapabilities

public weka.core.Capabilities getCapabilities()

Returns the Capabilities of this filter.

Specified by:

getCapabilities in interface weka.core.CapabilitiesHandler

Overrides:

getCapabilities in class weka.filters.Filter

Returns:

the capabilities of this object

See Also:

Capabilities

setInputFormat

public boolean setInputFormat(weka.core.Instances instanceInfo)
                       throws Exception

Overrides:

setInputFormat in class weka.filters.Filter

Throws:

Exception

input

public boolean input(weka.core.Instance instance)

Overrides:

input in class weka.filters.Filter

batchFinished

public boolean batchFinished()

Overrides:

batchFinished in class weka.filters.Filter