/// <summary>
/// Perform SSA change point detection over a column of time series data. See <see cref="SsaChangePointEstimator"/>.
/// </summary>
public static Vector <double> SsaChangePointDetect(
this Scalar <float> input,
int confidence,
int changeHistoryLength,
int trainingWindowSize,
int seasonalityWindowSize,
ErrorFunction errorFunction = ErrorFunction.SignedDifference,
MartingaleType martingale = MartingaleType.Power,
double eps = 0.1) => new OutColumn(input, confidence, changeHistoryLength, trainingWindowSize, seasonalityWindowSize, errorFunction, martingale, eps);
public OutColumn(
Scalar <float> input,
int confidence,
int changeHistoryLength,
MartingaleType martingale,
double eps)
: base(new Reconciler(confidence, changeHistoryLength, martingale, eps), input)
{
Input = input;
}
public static IEstimator <ITransformer> _DetectIidChangePoint(this MLContext MLContext, JToken componentObject)
{
string outputColumn = componentObject.Value <string>("OutputColumnName");
string inputColumn = componentObject.Value <string>("InputColumnName");
int confidence = componentObject.Value <int>("Confidence");
int changeHistory = componentObject.Value <int>("ChangeHistoryLength");
MartingaleType martingale = Enum.Parse <MartingaleType>(componentObject.Value <string>("MartingaleType"));
double eps = componentObject.Value <double>("Eps");
return(MLContext.Transforms.DetectIidChangePoint(outputColumn, inputColumn, confidence, changeHistory, martingale, eps));
}
public Reconciler(
int confidence,
int changeHistoryLength,
MartingaleType martingale,
double eps)
{
_confidence = confidence;
_changeHistoryLength = changeHistoryLength;
_martingale = martingale;
_eps = eps;
}
public OutColumn(Scalar <float> input,
int confidence,
int changeHistoryLength,
int trainingWindowSize,
int seasonalityWindowSize,
ErrorFunction errorFunction,
MartingaleType martingale,
double eps)
: base(new Reconciler(confidence, changeHistoryLength, trainingWindowSize, seasonalityWindowSize, errorFunction, martingale, eps), input)
{
Input = input;
}
/// <summary>
/// Create a new instance of <see cref="IidChangePointEstimator"/>
/// </summary>
/// <param name="env">Host Environment.</param>
/// <param name="inputColumn">Name of the input column.</param>
/// <param name="outputColumn">Name of the output column. Column is a vector of type double and size 4.
/// The vector contains Alert, Raw Score, P-Value and Martingale score as first four values.</param>
/// <param name="confidence">The confidence for change point detection in the range [0, 100].</param>
/// <param name="changeHistoryLength">The length of the sliding window on p-values for computing the martingale score.</param>
/// <param name="martingale">The martingale used for scoring.</param>
/// <param name="eps">The epsilon parameter for the Power martingale.</param>
public IidChangePointEstimator(IHostEnvironment env, string inputColumn, string outputColumn, int confidence,
int changeHistoryLength, MartingaleType martingale = MartingaleType.Power, double eps = 0.1)
: base(Contracts.CheckRef(env, nameof(env)).Register(nameof(IidChangePointEstimator)),
new IidChangePointDetector(env, new IidChangePointDetector.Arguments
{
Name = outputColumn,
Source = inputColumn,
Confidence = confidence,
ChangeHistoryLength = changeHistoryLength,
Martingale = martingale,
PowerMartingaleEpsilon = eps
}))
{
}
/// <summary>
/// Create <see cref="SsaChangePointEstimator"/>, which predicts change points in time series
/// using <a href="https://en.wikipedia.org/wiki/Singular_spectrum_analysis">Singular Spectrum Analysis (SSA)</a>.
/// </summary>
/// <param name="catalog">The transform's catalog.</param>
/// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.
/// The column data is a vector of <see cref="System.Double"/>. The vector contains 4 elements: alert (non-zero value means a change point), raw score, p-Value and martingale score.</param>
/// <param name="inputColumnName">Name of column to transform. The column data must be <see cref="System.Single"/>.
/// If set to <see langword="null"/>, the value of the <paramref name="outputColumnName"/> will be used as source.</param>
/// <param name="confidence">The confidence for change point detection in the range [0, 100].</param>
/// <param name="trainingWindowSize">The number of points from the beginning of the sequence used for training.</param>
/// <param name="changeHistoryLength">The size of the sliding window for computing the p-value.</param>
/// <param name="seasonalityWindowSize">An upper bound on the largest relevant seasonality in the input time-series.</param>
/// <param name="errorFunction">The function used to compute the error between the expected and the observed value.</param>
/// <param name="martingale">The martingale used for scoring.</param>
/// <param name="eps">The epsilon parameter for the Power martingale.</param>
/// <example>
/// <format type="text/markdown">
/// <]
/// ]]>
/// </format>
/// </example>
public static SsaChangePointEstimator DetectChangePointBySsa(this TransformsCatalog catalog, string outputColumnName, string inputColumnName,
int confidence, int changeHistoryLength, int trainingWindowSize, int seasonalityWindowSize, ErrorFunction errorFunction = ErrorFunction.SignedDifference,
MartingaleType martingale = MartingaleType.Power, double eps = 0.1)
=> new SsaChangePointEstimator(CatalogUtils.GetEnvironment(catalog), new SsaChangePointDetector.Options
{
Name = outputColumnName,
Source = inputColumnName ?? outputColumnName,
Confidence = confidence,
ChangeHistoryLength = changeHistoryLength,
TrainingWindowSize = trainingWindowSize,
SeasonalWindowSize = seasonalityWindowSize,
Martingale = martingale,
PowerMartingaleEpsilon = eps,
ErrorFunction = errorFunction
});
public static IEstimator <ITransformer> _DetectChangePointBySsa(this MLContext MLContext, JToken componentObject)
{
string outputColumn = componentObject.Value <string>("OutputColumnName");
string inputColumn = componentObject.Value <string>("InputColumnName");
int confidence = componentObject.Value <int>("Confidence");
int changeHistory = componentObject.Value <int>("ChangeHistoryLength");
int trainingWindow = componentObject.Value <int>("TrainingWindowSize");
int seasonalityWindow = componentObject.Value <int>("SeasonalityWindowSize");
ErrorFunction errorFunction = Enum.Parse <ErrorFunction>(componentObject.Value <string>("ErrorFunction"));
MartingaleType martingale = Enum.Parse <MartingaleType>(componentObject.Value <string>("MartingaleType"));
double eps = componentObject.Value <double>("Eps");
return(MLContext.Transforms.DetectChangePointBySsa(outputColumn, inputColumn, confidence, changeHistory,
trainingWindow, seasonalityWindow, errorFunction,
martingale, eps));
}
public Reconciler(
int confidence,
int changeHistoryLength,
int trainingWindowSize,
int seasonalityWindowSize,
ErrorFunction errorFunction,
MartingaleType martingale,
double eps)
{
_confidence = confidence;
_changeHistoryLength = changeHistoryLength;
_trainingWindowSize = trainingWindowSize;
_seasonalityWindowSize = seasonalityWindowSize;
_errorFunction = errorFunction;
_martingale = martingale;
_eps = eps;
}
/// <summary>
/// Create a new instance of <see cref="SsaChangePointEstimator"/>
/// </summary>
/// <param name="env">Host Environment.</param>
/// <param name="inputColumn">Name of the input column.</param>
/// <param name="outputColumn">Name of the output column.</param>
/// <param name="confidence">The confidence for change point detection in the range [0, 100].</param>
/// <param name="trainingWindowSize">The number of points from the beginning of the sequence used for training.</param>
/// <param name="changeHistoryLength">The size of the sliding window for computing the p-value.</param>
/// <param name="seasonalityWindowSize">An upper bound on the largest relevant seasonality in the input time-series.</param>
/// <param name="errorFunction">The function used to compute the error between the expected and the observed value.</param>
/// <param name="martingale">The martingale used for scoring.</param>
/// <param name="eps">The epsilon parameter for the Power martingale.</param>
/// <p>Example code can be found by searching for <i>SsaChangePointDetector</i> in <a href='https://github.com/dotnet/machinelearning'>ML.NET.</a></p>
/// <example>
/// <format type="text/markdown">
/// <]
/// ]]>
/// </format>
/// </example>
public SsaChangePointEstimator(IHostEnvironment env, string inputColumn, string outputColumn,
int confidence, int changeHistoryLength, int trainingWindowSize, int seasonalityWindowSize,
ErrorFunctionUtils.ErrorFunction errorFunction = ErrorFunctionUtils.ErrorFunction.SignedDifference,
MartingaleType martingale = MartingaleType.Power, double eps = 0.1)
: this(env, new SsaChangePointDetector.Arguments
{
Name = outputColumn,
Source = inputColumn,
Confidence = confidence,
ChangeHistoryLength = changeHistoryLength,
TrainingWindowSize = trainingWindowSize,
SeasonalWindowSize = seasonalityWindowSize,
Martingale = martingale,
PowerMartingaleEpsilon = eps,
ErrorFunction = errorFunction
})
{
}
protected SequentialAnomalyDetectionTransformBase(IHostEnvironment env, ModelLoadContext ctx, string name, IDataView input)
: base(env, ctx, name, input)
{
// *** Binary format ***
// <base>
// byte: _martingale
// byte: _alertingScore
// byte: _anomalySide
// Double: _powerMartingaleEpsilon
// Double: _alertThreshold
byte temp;
temp = ctx.Reader.ReadByte();
Host.CheckDecode(Enum.IsDefined(typeof(MartingaleType), temp));
Martingale = (MartingaleType)temp;
temp = ctx.Reader.ReadByte();
Host.CheckDecode(Enum.IsDefined(typeof(AlertingScore), temp));
ThresholdScore = (AlertingScore)temp;
Host.CheckDecode(Martingale != MartingaleType.None || ThresholdScore != AlertingScore.MartingaleScore);
Host.CheckDecode(WindowSize > 0 || ThresholdScore == AlertingScore.RawScore);
temp = ctx.Reader.ReadByte();
Host.CheckDecode(Enum.IsDefined(typeof(AnomalySide), temp));
Side = (AnomalySide)temp;
PowerMartingaleEpsilon = ctx.Reader.ReadDouble();
Host.CheckDecode(0 < PowerMartingaleEpsilon && PowerMartingaleEpsilon < 1);
AlertThreshold = ctx.Reader.ReadDouble();
Host.CheckDecode(AlertThreshold >= 0);
Host.CheckDecode(ThresholdScore != AlertingScore.PValueScore || (0 <= AlertThreshold && AlertThreshold <= 1));
_outputLength = GetOutputLength(ThresholdScore, Host);
_wrappedSchema = CreateSchema(base.Schema, OutputColumnName, _outputLength);
}
private protected SequentialAnomalyDetectionTransformBase(int windowSize, int initialWindowSize, string inputColumnName, string outputColumnName, string name, IHostEnvironment env,
AnomalySide anomalySide, MartingaleType martingale, AlertingScore alertingScore, Double powerMartingaleEpsilon,
Double alertThreshold)
: base(Contracts.CheckRef(env, nameof(env)).Register(name), windowSize, initialWindowSize, outputColumnName, inputColumnName, new VectorType(NumberDataViewType.Double, GetOutputLength(alertingScore, env)))
{
Host.CheckUserArg(Enum.IsDefined(typeof(MartingaleType), martingale), nameof(ArgumentsBase.Martingale), "Value is undefined.");
Host.CheckUserArg(Enum.IsDefined(typeof(AnomalySide), anomalySide), nameof(ArgumentsBase.Side), "Value is undefined.");
Host.CheckUserArg(Enum.IsDefined(typeof(AlertingScore), alertingScore), nameof(ArgumentsBase.AlertOn), "Value is undefined.");
Host.CheckUserArg(martingale != MartingaleType.None || alertingScore != AlertingScore.MartingaleScore, nameof(ArgumentsBase.Martingale), "A martingale type should be specified if alerting is based on the martingale score.");
Host.CheckUserArg(windowSize > 0 || alertingScore == AlertingScore.RawScore, nameof(ArgumentsBase.AlertOn),
"When there is no windowed buffering (i.e., " + nameof(ArgumentsBase.WindowSize) + " = 0), the alert can be generated only based on the raw score (i.e., "
+ nameof(ArgumentsBase.AlertOn) + " = " + nameof(AlertingScore.RawScore) + ")");
Host.CheckUserArg(0 < powerMartingaleEpsilon && powerMartingaleEpsilon < 1, nameof(ArgumentsBase.PowerMartingaleEpsilon), "Should be in (0,1).");
Host.CheckUserArg(alertThreshold >= 0, nameof(ArgumentsBase.AlertThreshold), "Must be non-negative.");
Host.CheckUserArg(alertingScore != AlertingScore.PValueScore || (0 <= alertThreshold && alertThreshold <= 1), nameof(ArgumentsBase.AlertThreshold), "Must be in [0,1].");
ThresholdScore = alertingScore;
Side = anomalySide;
Martingale = martingale;
PowerMartingaleEpsilon = powerMartingaleEpsilon;
AlertThreshold = alertThreshold;
OutputLength = GetOutputLength(ThresholdScore, Host);
}
private protected SequentialAnomalyDetectionTransformBase(IHostEnvironment env, ModelLoadContext ctx, string name)
: base(Contracts.CheckRef(env, nameof(env)).Register(name), ctx)
{
// *** Binary format ***
// <base>
// byte: _martingale
// byte: _alertingScore
// byte: _anomalySide
// Double: _powerMartingaleEpsilon
// Double: _alertThreshold
byte temp;
temp = ctx.Reader.ReadByte();
Host.CheckDecode(Enum.IsDefined(typeof(MartingaleType), temp));
Martingale = (MartingaleType)temp;
temp = ctx.Reader.ReadByte();
Host.CheckDecode(Enum.IsDefined(typeof(AlertingScore), temp));
ThresholdScore = (AlertingScore)temp;
Host.CheckDecode(Martingale != MartingaleType.None || ThresholdScore != AlertingScore.MartingaleScore);
Host.CheckDecode(WindowSize > 0 || ThresholdScore == AlertingScore.RawScore);
temp = ctx.Reader.ReadByte();
Host.CheckDecode(Enum.IsDefined(typeof(AnomalySide), temp));
Side = (AnomalySide)temp;
PowerMartingaleEpsilon = ctx.Reader.ReadDouble();
Host.CheckDecode(0 < PowerMartingaleEpsilon && PowerMartingaleEpsilon < 1);
AlertThreshold = ctx.Reader.ReadDouble();
Host.CheckDecode(AlertThreshold >= 0);
Host.CheckDecode(ThresholdScore != AlertingScore.PValueScore || (0 <= AlertThreshold && AlertThreshold <= 1));
OutputLength = GetOutputLength(ThresholdScore, Host);
}
/// <summary>
/// Perform IID change point detection over a column of time series data. See <see cref="IidChangePointEstimator"/>.
/// </summary>
public static Vector <double> IidChangePointDetect(
this Scalar <float> input,
int confidence,
int changeHistoryLength,
MartingaleType martingale = MartingaleType.Power,
double eps = 0.1) => new OutColumn(input, confidence, changeHistoryLength, martingale, eps);
public static SsaChangePointEstimator DetectChangePointBySsa(this TransformsCatalog catalog, string outputColumnName, string inputColumnName,
int confidence, int changeHistoryLength, int trainingWindowSize, int seasonalityWindowSize, ErrorFunction errorFunction = ErrorFunction.SignedDifference,
MartingaleType martingale = MartingaleType.Power, double eps = 0.1)
=> DetectChangePointBySsa(catalog, outputColumnName, inputColumnName, (double)confidence, changeHistoryLength, trainingWindowSize, seasonalityWindowSize, errorFunction, martingale, eps);
public static IidChangePointEstimator DetectIidChangePoint(this TransformsCatalog catalog, string outputColumnName, string inputColumnName,
int confidence, int changeHistoryLength, MartingaleType martingale = MartingaleType.Power, double eps = 0.1)
=> DetectIidChangePoint(catalog, outputColumnName, inputColumnName, (double)confidence, changeHistoryLength, martingale, eps);
/// <summary>
/// Create <see cref="IidChangePointEstimator"/>, which predicts change points in an
/// <a href="https://en.wikipedia.org/wiki/Independent_and_identically_distributed_random_variables">independent identically distributed (i.i.d.)</a>
/// time series based on adaptive kernel density estimations and martingale scores.
/// </summary>
/// <param name="catalog">The transform's catalog.</param>
/// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.
/// The column data is a vector of <see cref="System.Double"/>. The vector contains 4 elements: alert (non-zero value means a change point), raw score, p-Value and martingale score.</param>
/// <param name="inputColumnName">Name of column to transform. The column data must be <see cref="System.Single"/>. If set to <see langword="null"/>, the value of the <paramref name="outputColumnName"/> will be used as source.</param>
/// <param name="confidence">The confidence for change point detection in the range [0, 100].</param>
/// <param name="changeHistoryLength">The length of the sliding window on p-values for computing the martingale score.</param>
/// <param name="martingale">The martingale used for scoring.</param>
/// <param name="eps">The epsilon parameter for the Power martingale.</param>
/// <example>
/// <format type="text/markdown">
/// <]
/// ]]>
/// </format>
/// </example>
public static IidChangePointEstimator DetectIidChangePoint(this TransformsCatalog catalog, string outputColumnName, string inputColumnName,
int confidence, int changeHistoryLength, MartingaleType martingale = MartingaleType.Power, double eps = 0.1)
=> new IidChangePointEstimator(CatalogUtils.GetEnvironment(catalog), outputColumnName, confidence, changeHistoryLength, inputColumnName, martingale, eps);
