Skip to content

Commit 82dd186

Browse files
Ivanidzo4kaIvanidzo4ka
authored
SymSGD documentation (#3345)
1 parent 8644b3b commit 82dd186

File tree

6 files changed

+43
-39
lines changed

6 files changed

+43
-39
lines changed

‎docs/api-reference/io-columns-binary-classification.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@ The input label column data must be <xref:System.Single>. This trainer outputs t
44
| Output Column Name | Column Type | Description|
55
| -- | -- | -- |
66
| `Score` | <xref:System.Single> | The unbounded score that was calculated by the trainer to determine the prediction.|
7-
| `PredictedLabel` | <xref:System.Boolean> | The label predicted by the trainer. `false` maps to negative score and `true` maps to positive score.|
8-
| `Probability` | <xref:System.Single> | The probability of the score in range [0, 1].|
7+
| `PredictedLabel` | <xref:System.Boolean> | The label predicted by the trainer. `false` maps to negative score and `true` maps to positive score.|
8+
| `Probability` | <xref:System.Single> | The probability of having true as the label. Probability value is in range [0, 1].||

‎src/Microsoft.ML.Mkl.Components.StaticPipe/VectorWhiteningStaticExtensions.cs

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,6 @@ public override IEstimator<ITransformer> Reconcile(IHostEnvironment env,
5656
}
5757
}
5858

59-
/// <include file='../Microsoft.ML.Mkl.Components/doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
6059
/// <param name="input">The column to which the transform will be applied.</param>
6160
/// <param name="eps">Whitening constant, prevents division by zero when scaling the data by inverse of eigenvalues.</param>
6261
/// <param name="maxRows">Maximum number of rows used to train the transform.</param>
@@ -67,7 +66,6 @@ public static Vector<float> PcaWhitening(this Vector<float> input,
6766
int pcaNum = VectorWhiteningEstimator.Defaults.Rank)
6867
=> new OutPipelineColumn(input, WhiteningKind.PrincipalComponentAnalysis, eps, maxRows, pcaNum);
6968

70-
/// <include file='../Microsoft.ML.Mkl.Components/doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
7169
/// <param name="input">The column to which the transform will be applied.</param>
7270
/// <param name="eps">Whitening constant, prevents division by zero.</param>
7371
/// <param name="maxRows">Maximum number of rows used to train the transform.</param>

‎src/Microsoft.ML.Mkl.Components/MklComponentsCatalog.cs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -69,13 +69,13 @@ public static OlsTrainer Ols(
6969
}
7070

7171
/// <summary>
72-
/// Predict a target using a linear binary classification model trained with the <see cref="SymbolicSgdLogisticRegressionBinaryTrainer"/>.
72+
/// Create an <see cref="SymbolicSgdLogisticRegressionBinaryTrainer"/> with advanced options, which predicts a target using a linear binary classification model trained over boolean label data.
7373
/// Stochastic gradient descent (SGD) is an iterative algorithm that optimizes a differentiable objective function.
7474
/// The <see cref="SymbolicSgdLogisticRegressionBinaryTrainer"/> parallelizes SGD using <a href="https://www.microsoft.com/en-us/research/project/project-parade/#!symbolic-execution">symbolic execution</a>.
7575
/// </summary>
7676
/// <param name="catalog">The <see cref="BinaryClassificationCatalog"/>.</param>
77-
/// <param name="labelColumnName">The name of the label column.</param>
78-
/// <param name="featureColumnName">The name of the feature column.</param>
77+
/// <param name="labelColumnName">The name of the label column. The column data must be <see cref="System.Boolean"/>.</param>
78+
/// <param name="featureColumnName">The name of the feature column. The column data must be a known-sized vector of <see cref="System.Single"/>.</param>
7979
/// <param name="numberOfIterations">Number of training iterations.</param>
8080
/// <example>
8181
/// <format type="text/markdown">
@@ -102,7 +102,7 @@ public static SymbolicSgdLogisticRegressionBinaryTrainer SymbolicSgdLogisticRegr
102102
}
103103

104104
/// <summary>
105-
/// Predict a target using a linear binary classification model trained with the <see cref="SymbolicSgdLogisticRegressionBinaryTrainer"/>.
105+
/// Create an<see cref= "SymbolicSgdLogisticRegressionBinaryTrainer" />, which predicts a target using a linear binary classification model trained over boolean label data.
106106
/// Stochastic gradient descent (SGD) is an iterative algorithm that optimizes a differentiable objective function.
107107
/// The <see cref="SymbolicSgdLogisticRegressionBinaryTrainer"/> parallelizes SGD using <a href="https://www.microsoft.com/en-us/research/project/project-parade/#!symbolic-execution">symbolic execution</a>.
108108
/// </summary>

‎src/Microsoft.ML.Mkl.Components/SymSgdClassificationTrainer.cs

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,14 +31,49 @@ namespace Microsoft.ML.Trainers
3131
{
3232
using TPredictor = CalibratedModelParametersBase<LinearBinaryModelParameters, PlattCalibrator>;
3333

34-
/// <include file='doc.xml' path='doc/members/member[@name="SymSGD"]/*' />
34+
/// <summary>
35+
/// The <see cref="IEstimator{TTransformer}"/> to predict a target using a linear binary classification model trained with the symbolic stochastic gradient descent.
36+
/// </summary>
37+
/// <remarks>
38+
/// <format type="text/markdown"><![CDATA[
39+
/// To create this trainer, use [SymbolicStochasticGradientDescent](xref:Microsoft.ML.MklComponentsCatalog.SymbolicSgdLogisticRegression(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,System.String,System.String,System.Int32)
40+
/// or [SymbolicStochasticGradientDescent(Options)](xref:Microsoft.ML.MklComponentsCatalog.SymbolicSgdLogisticRegression(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,Microsoft.ML.Trainers.SymbolicSgdLogisticRegressionBinaryTrainer.Options).
41+
///
42+
/// [!include[io](~/../docs/samples/docs/api-reference/io-columns-binary-classification.md)]
43+
///
44+
/// ### Trainer Characteristics
45+
/// | | |
46+
/// | -- | -- |
47+
/// | Machine learning task | Binary classification |
48+
/// | Is normalization required? | Yes |
49+
/// | Is caching required? | No |
50+
/// | Required NuGet in addition to Microsoft.ML |Microsoft.ML.Mkl.Components |
51+
/// ### Training Algorithm Details
52+
/// The symbolic SGD is a classification algorithm that makes its predictions by finding a separating hyperplane.
53+
/// For instance, with feature values $f0, f1,..., f_{D-1}$, the prediction is given by determining what side of the hyperplane the point falls into.
54+
/// That is the same as the sign of the feautures' weighted sum, i.e. $\sum_{i = 0}^{D-1} (w_i * f_i)$, where $w_0, w_1,..., w_{D-1}$ are the weights computed by the algorithm.
55+
///
56+
/// While most of SGD algorithms is inherently sequential - at each step, the processing of the current example depends on the parameters learned from previous examples.
57+
/// This algorithm trains local models in separate threads and probabilistic model cobminer that allows the local models to be combined
58+
/// to produce the same result as what a sequential SGD would have produced, in expectation.
59+
///
60+
/// For more information see [Parallel Stochastic Gradient Descent with Sound Combiners](https://arxiv.org/abs/1705.08030).
61+
/// ]]>
62+
/// </format>
63+
/// </remarks>
64+
/// <seealso cref="MklComponentsCatalog.SymbolicSgdLogisticRegression(BinaryClassificationCatalog.BinaryClassificationTrainers, string, string, int)" />
65+
/// <seealso cref="MklComponentsCatalog.SymbolicSgdLogisticRegression(BinaryClassificationCatalog.BinaryClassificationTrainers, Options)"/>
66+
/// <seealso cref="Options"/>
3567
public sealed class SymbolicSgdLogisticRegressionBinaryTrainer : TrainerEstimatorBase<BinaryPredictionTransformer<TPredictor>, TPredictor>
3668
{
3769
internal const string LoadNameValue = "SymbolicSGD";
3870
internal const string UserNameValue = "Symbolic SGD (binary)";
3971
internal const string ShortName = "SymSGD";
4072

41-
///<summary> Advanced options for trainer.</summary>
73+
/// <summary>
74+
/// Options for the <see cref="SymbolicSgdLogisticRegressionBinaryTrainer"/> as used in
75+
/// [SymbolicStochasticGradientDescent(Options)](xref:Microsoft.ML.MklComponentsCatalog.SymbolicSgdLogisticRegression(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,Microsoft.ML.Trainers.SymbolicSgdLogisticRegressionBinaryTrainer.Options).
76+
/// </summary>
4277
public sealed class Options : TrainerInputBaseWithLabel
4378
{
4479
/// <summary>

‎src/Microsoft.ML.Mkl.Components/VectorWhitening.cs

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,6 @@ public enum WhiteningKind
4646
ZeroPhaseComponentAnalysis
4747
}
4848

49-
/// <include file='doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
5049
public sealed class VectorWhiteningTransformer : OneToOneTransformerBase
5150
{
5251
internal sealed class Options
@@ -666,7 +665,6 @@ private static float DotProduct(float[] a, int aOffset, ReadOnlySpan<float> b, R
666665
}
667666
}
668667

669-
/// <include file='doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
670668
public sealed class VectorWhiteningEstimator : IEstimator<VectorWhiteningTransformer>
671669
{
672670
[BestFriend]
@@ -801,7 +799,6 @@ internal void Save(ModelSaveContext ctx)
801799
private readonly IHost _host;
802800
private readonly ColumnOptions[] _infos;
803801

804-
/// <include file='doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
805802
/// <param name="env">The environment.</param>
806803
/// <param name="columns">Describes the parameters of the whitening process for each column pair.</param>
807804
internal VectorWhiteningEstimator(IHostEnvironment env, params ColumnOptions[] columns)
@@ -810,7 +807,6 @@ internal VectorWhiteningEstimator(IHostEnvironment env, params ColumnOptions[] c
810807
_infos = columns;
811808
}
812809

813-
/// <include file='doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
814810
/// <param name="env">The environment.</param>
815811
/// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
816812
/// <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>

‎src/Microsoft.ML.Mkl.Components/doc.xml

Lines changed: 0 additions & 25 deletions
This file was deleted.

0 commit comments

Comments
 (0)