public ColInfoEx(ModelLoadContext ctx, ColInfo info)
{
Contracts.AssertValue(ctx);
// *** Binary format ***
// int: kind
// Float: epsilon
// int: maxrow
// byte: saveInv
// int: pcaNum
Kind = (WhiteningKind)ctx.Reader.ReadInt32();
Contracts.CheckDecode(Kind == WhiteningKind.Pca || Kind == WhiteningKind.Zca);
Epsilon = ctx.Reader.ReadFloat();
Contracts.CheckDecode(0 <= Epsilon && Epsilon < Float.PositiveInfinity);
MaxRow = ctx.Reader.ReadInt32();
Contracts.CheckDecode(MaxRow > 0);
SaveInv = ctx.Reader.ReadBoolByte();
PcaNum = ctx.Reader.ReadInt32();
Contracts.CheckDecode(PcaNum >= 0);
if (Kind == WhiteningKind.Zca || PcaNum == 0)
{
Type = info.TypeSrc.AsVector;
}
else
{
Type = new VectorType(NumberType.Float, PcaNum); // REVIEW: make it work with pcaNum == 1.
}
}
/// <summary>
/// Takes column filled with a vector of random variables with a known covariance matrix into a set of new variables whose covariance is the identity matrix,
/// meaning that they are uncorrelated and each have variance 1.
/// </summary>
/// <param name="catalog">The transform's catalog.</param>
/// <param name="inputColumn">Name of the input column.</param>
/// <param name="outputColumn">Name of the column resulting from the transformation of <paramref name="inputColumn"/>.
/// Null means <paramref name="inputColumn"/> is replaced. </param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
/// <param name="eps">Whitening constant, prevents division by zero.</param>
/// <param name="maxRows">Maximum number of rows used to train the transform.</param>
/// <param name="pcaNum">In case of PCA whitening, indicates the number of components to retain.</param>
/// <example>
/// <format type="text/markdown">
/// <]
/// ]]>
/// </format>
/// </example>
public static VectorWhiteningEstimator VectorWhiten(this TransformsCatalog.ProjectionTransforms catalog,
string inputColumn, string outputColumn = null,
WhiteningKind kind = VectorWhiteningTransformer.Defaults.Kind,
float eps = VectorWhiteningTransformer.Defaults.Eps,
int maxRows = VectorWhiteningTransformer.Defaults.MaxRows,
int pcaNum = VectorWhiteningTransformer.Defaults.PcaNum)
=> new VectorWhiteningEstimator(CatalogUtils.GetEnvironment(catalog), inputColumn, outputColumn, kind, eps, maxRows, pcaNum);
public Reconciler(WhiteningKind kind, float eps, int maxRows, int pcaNum)
{
_kind = kind;
_eps = eps;
_maxRows = maxRows;
_pcaNum = pcaNum;
}
public Reconciler(WhiteningKind kind, float eps, int maxRows, bool saveInverse, int pcaNum)
{
_kind = kind;
_eps = eps;
_maxRows = maxRows;
_saveInverse = saveInverse;
_pcaNum = pcaNum;
}
/// <include file='doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
/// <param name="env">The environment.</param>
/// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
/// <param name="inputColumnName">Name of column to transform. If set to <see langword="null"/>, the value of the <paramref name="outputColumnName"/> will be used as source.</param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
/// <param name="eps">Whitening constant, prevents division by zero when scaling the data by inverse of eigenvalues.</param>
/// <param name="maxRows">Maximum number of rows used to train the transform.</param>
/// <param name="pcaNum">In case of PCA whitening, indicates the number of components to retain.</param>
internal VectorWhiteningEstimator(IHostEnvironment env, string outputColumnName, string inputColumnName = null,
WhiteningKind kind = Defaults.Kind,
float eps = Defaults.Eps,
int maxRows = Defaults.MaxRows,
int pcaNum = Defaults.PcaNum)
: this(env, new ColumnInfo(outputColumnName, inputColumnName, kind, eps, maxRows, pcaNum))
{
}
/// <summary>
/// Convenience constructor for public facing API.
/// </summary>
/// <param name="env">Host Environment.</param>
/// <param name="input">Input <see cref="IDataView"/>. This is the output from previous transform or loader.</param>
/// <param name="name">Name of the output column.</param>
/// <param name="source">Name of the column to be transformed. If this is null '<paramref name="name"/>' will be used.</param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
public WhiteningTransform(IHostEnvironment env,
IDataView input,
string name,
string source = null,
WhiteningKind kind = Defaults.Kind)
: this(env, new Arguments() { Column = new[] { new Column() { Source = source ?? name, Name = name } }, Kind = kind }, input)
{
}
/// <include file='doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
/// <param name="env">The environment.</param>
/// <param name="inputColumn">Name of the input column.</param>
/// <param name="outputColumn">Name of the column resulting from the transformation of <paramref name="inputColumn"/>. Null means <paramref name="inputColumn"/> is replaced.</param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
/// <param name="eps">Whitening constant, prevents division by zero when scaling the data by inverse of eigenvalues.</param>
/// <param name="maxRows">Maximum number of rows used to train the transform.</param>
/// <param name="pcaNum">In case of PCA whitening, indicates the number of components to retain.</param>
public VectorWhiteningEstimator(IHostEnvironment env, string inputColumn, string outputColumn,
WhiteningKind kind = VectorWhiteningTransformer.Defaults.Kind,
float eps = VectorWhiteningTransformer.Defaults.Eps,
int maxRows = VectorWhiteningTransformer.Defaults.MaxRows,
int pcaNum = VectorWhiteningTransformer.Defaults.PcaNum)
: this(env, new VectorWhiteningTransformer.ColumnInfo(inputColumn, outputColumn, kind, eps, maxRows, pcaNum))
{
}
/// <param name="env">The environment.</param>
/// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
/// <param name="inputColumnName">Name of column to transform. If set to <see langword="null"/>, the value of the <paramref name="outputColumnName"/> will be used as source.</param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
/// <param name="epsilon">Whitening constant, prevents division by zero when scaling the data by inverse of eigenvalues.</param>
/// <param name="maximumNumberOfRows">Maximum number of rows used to train the transform.</param>
/// <param name="rank">In case of PCA whitening, indicates the number of components to retain.</param>
internal VectorWhiteningEstimator(IHostEnvironment env, string outputColumnName, string inputColumnName = null,
WhiteningKind kind = Defaults.Kind,
float epsilon = Defaults.Epsilon,
int maximumNumberOfRows = Defaults.MaximumNumberOfRows,
int rank = Defaults.Rank)
: this(env, new ColumnOptions(outputColumnName, inputColumnName, kind, epsilon, maximumNumberOfRows, rank))
{
}
internal ColumnInfo(Column item, Arguments args)
{
Input = item.Source ?? item.Name;
Contracts.CheckValue(Input, nameof(Input));
Output = item.Name;
Contracts.CheckValue(Output, nameof(Output));
Kind = item.Kind ?? args.Kind;
Contracts.CheckUserArg(Kind == WhiteningKind.Pca || Kind == WhiteningKind.Zca, nameof(item.Kind));
Epsilon = item.Eps ?? args.Eps;
Contracts.CheckUserArg(0 <= Epsilon && Epsilon < float.PositiveInfinity, nameof(item.Eps));
MaxRow = item.MaxRows ?? args.MaxRows;
Contracts.CheckUserArg(MaxRow > 0, nameof(item.MaxRows));
SaveInv = item.SaveInverse ?? args.SaveInverse;
PcaNum = item.PcaNum ?? args.PcaNum;
Contracts.CheckUserArg(PcaNum >= 0, nameof(item.PcaNum));
}
internal ColumnOptions(VectorWhiteningTransformer.Column item, VectorWhiteningTransformer.Options options)
{
Name = item.Name;
Contracts.CheckValue(Name, nameof(Name));
InputColumnName = item.Source ?? item.Name;
Contracts.CheckValue(InputColumnName, nameof(InputColumnName));
Kind = item.Kind ?? options.Kind;
Contracts.CheckUserArg(Kind == WhiteningKind.PrincipalComponentAnalysis || Kind == WhiteningKind.ZeroPhaseComponentAnalysis, nameof(item.Kind));
Epsilon = item.Eps ?? options.Eps;
Contracts.CheckUserArg(0 <= Epsilon && Epsilon < float.PositiveInfinity, nameof(item.Eps));
MaximumNumberOfRows = item.MaxRows ?? options.MaxRows;
Contracts.CheckUserArg(MaximumNumberOfRows > 0, nameof(item.MaxRows));
SaveInv = item.SaveInverse ?? options.SaveInverse;
Rank = item.PcaNum ?? options.PcaNum;
Contracts.CheckUserArg(Rank >= 0, nameof(item.PcaNum));
}
internal ColumnInfo(VectorWhiteningTransformer.Column item, VectorWhiteningTransformer.Options options)
{
Name = item.Name;
Contracts.CheckValue(Name, nameof(Name));
InputColumnName = item.Source ?? item.Name;
Contracts.CheckValue(InputColumnName, nameof(InputColumnName));
Kind = item.Kind ?? options.Kind;
Contracts.CheckUserArg(Kind == WhiteningKind.Pca || Kind == WhiteningKind.Zca, nameof(item.Kind));
Epsilon = item.Eps ?? options.Eps;
Contracts.CheckUserArg(0 <= Epsilon && Epsilon < float.PositiveInfinity, nameof(item.Eps));
MaxRow = item.MaxRows ?? options.MaxRows;
Contracts.CheckUserArg(MaxRow > 0, nameof(item.MaxRows));
SaveInv = item.SaveInverse ?? options.SaveInverse;
PcaNum = item.PcaNum ?? options.PcaNum;
Contracts.CheckUserArg(PcaNum >= 0, nameof(item.PcaNum));
}
/// <summary>
/// Describes how the transformer handles one input-output column pair.
/// </summary>
/// <param name="name">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
/// <param name="inputColumnName">Name of column to transform. If set to <see langword="null"/>, the value of the <paramref name="name"/> will be used as source.</param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
/// <param name="eps">Whitening constant, prevents division by zero.</param>
/// <param name="maxRows">Maximum number of rows used to train the transform.</param>
/// <param name="pcaNum">In case of PCA whitening, indicates the number of components to retain.</param>
public ColumnOptions(string name, string inputColumnName = null, WhiteningKind kind = Defaults.Kind, float eps = Defaults.Eps,
int maxRows = Defaults.MaxRows, int pcaNum = Defaults.PcaNum)
{
Name = name;
Contracts.CheckValue(Name, nameof(Name));
InputColumnName = inputColumnName ?? name;
Contracts.CheckValue(InputColumnName, nameof(InputColumnName));
Kind = kind;
Contracts.CheckUserArg(Kind == WhiteningKind.Pca || Kind == WhiteningKind.Zca, nameof(Kind));
Epsilon = eps;
Contracts.CheckUserArg(0 <= Epsilon && Epsilon < float.PositiveInfinity, nameof(Epsilon));
MaxRow = maxRows;
Contracts.CheckUserArg(MaxRow > 0, nameof(MaxRow));
SaveInv = Defaults.SaveInverse;
PcaNum = pcaNum; // REVIEW: make it work with pcaNum == 1.
Contracts.CheckUserArg(PcaNum >= 0, nameof(PcaNum));
}
/// <summary>
/// Describes how the transformer handles one input-output column pair.
/// </summary>
/// <param name="input">Name of the input column.</param>
/// <param name="output">Name of the column resulting from the transformation of <paramref name="input"/>. Null means <paramref name="input"/> is replaced.</param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
/// <param name="eps">Whitening constant, prevents division by zero.</param>
/// <param name="maxRows">Maximum number of rows used to train the transform.</param>
/// <param name="pcaNum">In case of PCA whitening, indicates the number of components to retain.</param>
public ColumnInfo(string input, string output = null, WhiteningKind kind = Defaults.Kind, float eps = Defaults.Eps,
int maxRows = Defaults.MaxRows, int pcaNum = Defaults.PcaNum)
{
Input = input;
Contracts.CheckValue(Input, nameof(Input));
Output = output ?? input;
Contracts.CheckValue(Output, nameof(Output));
Kind = kind;
Contracts.CheckUserArg(Kind == WhiteningKind.Pca || Kind == WhiteningKind.Zca, nameof(Kind));
Epsilon = eps;
Contracts.CheckUserArg(0 <= Epsilon && Epsilon < float.PositiveInfinity, nameof(Epsilon));
MaxRow = maxRows;
Contracts.CheckUserArg(MaxRow > 0, nameof(MaxRow));
SaveInv = Defaults.SaveInverse;
PcaNum = pcaNum; // REVIEW: make it work with pcaNum == 1.
Contracts.CheckUserArg(PcaNum >= 0, nameof(PcaNum));
}
/// <summary>
/// Describes how the transformer handles one input-output column pair.
/// </summary>
/// <param name="name">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
/// <param name="inputColumnName">Name of column to transform. If set to <see langword="null"/>, the value of the <paramref name="name"/> will be used as source.</param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
/// <param name="epsilon">Whitening constant, prevents division by zero.</param>
/// <param name="maximumNumberOfRows">Maximum number of rows used to train the transform.</param>
/// <param name="rank">In case of PCA whitening, indicates the number of components to retain.</param>
public ColumnOptions(string name, string inputColumnName = null, WhiteningKind kind = Defaults.Kind, float epsilon = Defaults.Epsilon,
int maximumNumberOfRows = Defaults.MaximumNumberOfRows, int rank = Defaults.Rank)
{
Name = name;
Contracts.CheckValue(Name, nameof(Name));
InputColumnName = inputColumnName ?? name;
Contracts.CheckValue(InputColumnName, nameof(InputColumnName));
Kind = kind;
Contracts.CheckUserArg(Kind == WhiteningKind.PrincipalComponentAnalysis || Kind == WhiteningKind.ZeroPhaseComponentAnalysis, nameof(Kind));
Epsilon = epsilon;
Contracts.CheckUserArg(0 <= Epsilon && Epsilon < float.PositiveInfinity, nameof(Epsilon));
MaximumNumberOfRows = maximumNumberOfRows;
Contracts.CheckUserArg(MaximumNumberOfRows > 0, nameof(MaximumNumberOfRows));
SaveInv = Defaults.SaveInverse;
Rank = rank; // REVIEW: make it work with pcaNum == 1.
Contracts.CheckUserArg(Rank >= 0, nameof(Rank));
}
internal ColumnInfo(ModelLoadContext ctx)
{
Contracts.AssertValue(ctx);
// *** Binary format ***
// int: kind
// float: epsilon
// int: maxrow
// byte: saveInv
// int: pcaNum
Kind = (WhiteningKind)ctx.Reader.ReadInt32();
Contracts.CheckDecode(Kind == WhiteningKind.Pca || Kind == WhiteningKind.Zca);
Epsilon = ctx.Reader.ReadFloat();
Contracts.CheckDecode(0 <= Epsilon && Epsilon < float.PositiveInfinity);
MaxRow = ctx.Reader.ReadInt32();
Contracts.CheckDecode(MaxRow > 0);
SaveInv = ctx.Reader.ReadBoolByte();
PcaNum = ctx.Reader.ReadInt32();
Contracts.CheckDecode(PcaNum >= 0);
}
internal ColumnOptions(ModelLoadContext ctx)
{
Contracts.AssertValue(ctx);
// *** Binary format ***
// int: kind
// float: epsilon
// int: maxrow
// byte: saveInv
// int: pcaNum
Kind = (WhiteningKind)ctx.Reader.ReadInt32();
Contracts.CheckDecode(Kind == WhiteningKind.PrincipalComponentAnalysis || Kind == WhiteningKind.ZeroPhaseComponentAnalysis);
Epsilon = ctx.Reader.ReadFloat();
Contracts.CheckDecode(0 <= Epsilon && Epsilon < float.PositiveInfinity);
MaximumNumberOfRows = ctx.Reader.ReadInt32();
Contracts.CheckDecode(MaximumNumberOfRows > 0);
SaveInv = ctx.Reader.ReadBoolByte();
Rank = ctx.Reader.ReadInt32();
Contracts.CheckDecode(Rank >= 0);
}
public ColInfoEx(Column item, Arguments args, ColInfo info)
{
Kind = item.Kind ?? args.Kind;
Contracts.CheckUserArg(Kind == WhiteningKind.Pca || Kind == WhiteningKind.Zca, nameof(item.Kind));
Epsilon = item.Eps ?? args.Eps;
Contracts.CheckUserArg(0 <= Epsilon && Epsilon < Float.PositiveInfinity, nameof(item.Eps));
MaxRow = item.MaxRows ?? args.MaxRows;
Contracts.CheckUserArg(MaxRow > 0, nameof(item.MaxRows));
SaveInv = item.SaveInverse ?? args.SaveInverse;
PcaNum = item.PcaNum ?? args.PcaNum;
Contracts.CheckUserArg(PcaNum >= 0, nameof(item.PcaNum));
if (Kind == WhiteningKind.Zca || PcaNum == 0)
{
Type = info.TypeSrc.AsVector;
}
else
{
Type = new VectorType(NumberType.Float, PcaNum); // REVIEW: make it work with pcaNum == 1.
}
}
/// <summary>
/// Takes column filled with a vector of random variables with a known covariance matrix into a set of new variables whose covariance is the identity matrix,
/// meaning that they are uncorrelated and each have variance 1.
/// </summary>
/// <param name="catalog">The transform's catalog.</param>
/// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
/// <param name="inputColumnName">Name of the column to transform. If set to <see langword="null"/>, the value of the <paramref name="outputColumnName"/> will be used as source.</param>
/// <param name="kind">Whitening kind (PCA/ZCA).</param>
/// <param name="epsilon">Whitening constant, prevents division by zero.</param>
/// <param name="maximumNumberOfRows">Maximum number of rows used to train the transform.</param>
/// <param name="rank">In case of PCA whitening, indicates the number of components to retain.</param>
/// <example>
/// <format type="text/markdown">
/// <]
/// [!code-csharp[VectorWhiten](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/Projection/VectorWhitenWithOptions.cs)]
/// ]]>
/// </format>
/// </example>
public static VectorWhiteningEstimator VectorWhiten(this TransformsCatalog catalog, string outputColumnName, string inputColumnName = null,
WhiteningKind kind = VectorWhiteningEstimator.Defaults.Kind,
float epsilon = VectorWhiteningEstimator.Defaults.Epsilon,
int maximumNumberOfRows = VectorWhiteningEstimator.Defaults.MaximumNumberOfRows,
int rank = VectorWhiteningEstimator.Defaults.Rank)
=> new VectorWhiteningEstimator(CatalogUtils.GetEnvironment(catalog), outputColumnName, inputColumnName, kind, epsilon, maximumNumberOfRows, rank);
public OutPipelineColumn(Vector <float> input, WhiteningKind kind, float eps, int maxRows, int pcaNum)
: base(new Reconciler(kind, eps, maxRows, pcaNum), input)
{
Input = input;
}
