API reference - Updated trainer docs for AveragedPerceptron #3310

shmoradims · 2019-04-12T13:08:26Z

This PR applies the template discussed #3218 to AveragedPerceptron. It serves as reference PR for updating the rest of the trainers.

The following pages are best-effort (90%) recreation of what these changes will look like. Although some changes will only be visible this PR and checked in and preview site is updated.

Extension methods:

AveragedPerceptronTrainer

AveragedPerceptronTrainer.Options

codecov · 2019-04-12T13:46:15Z

Codecov Report

Merging #3310 into master will decrease coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #3310      +/-   ##
==========================================
- Coverage   72.64%   72.64%   -0.01%     
==========================================
  Files         807      807              
  Lines      145190   145191       +1     
  Branches    16223    16223              
==========================================
  Hits       105480   105480              
  Misses      35293    35293              
- Partials     4417     4418       +1

Flag	Coverage Δ
#Debug	`72.64% <ø> (-0.01%)`	⬇️
#production	`68.17% <ø> (-0.01%)`	⬇️
#test	`88.97% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
...dardTrainers/Standard/Online/AveragedPerceptron.cs	`89.7% <ø> (ø)`	⬆️
...oft.ML.StandardTrainers/StandardTrainersCatalog.cs	`92.34% <ø> (ø)`	⬆️
...StandardTrainers/Standard/LinearModelParameters.cs	`60.05% <0%> (-0.27%)`	⬇️
src/Microsoft.ML.FastTree/TreeTrainersCatalog.cs	`94.18% <0%> (ø)`	⬆️
.../Microsoft.ML.Data/Transforms/ExtensionsCatalog.cs	`100% <0%> (ø)`	⬆️
src/Microsoft.ML.Data/Transforms/ColumnCopying.cs	`85.43% <0%> (ø)`	⬆️
test/Microsoft.ML.Functional.Tests/ModelFiles.cs	`96.07% <0%> (ø)`	⬆️
src/Microsoft.ML.DataView/IDataView.cs	`100% <0%> (ø)`	⬆️
src/Microsoft.ML.Transforms/NormalizerCatalog.cs	`84.78% <0%> (ø)`	⬆️
src/Microsoft.ML.Core/Data/Repository.cs	`80.41% <0%> (+0.06%)`	⬆️

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs

sfilipi · 2019-04-12T17:37:37Z

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs

@@ -383,11 +383,11 @@ public static class StandardTrainersCatalog
        }

        /// <summary>
-        /// Predict a target using a linear binary classification model trained with <see cref="AveragedPerceptronTrainer"/>.
+        /// Create an <see cref="AveragedPerceptronTrainer"/>, which predicts a target using a linear binary classification model trained over boolean label data.


boolean label data [](start = 143, length = 18)

over a label of boolean data. #Resolved

Natalie voted for no change.

In reply to: 275001029 [](ancestors = 275001029)

sfilipi · 2019-04-12T17:38:16Z

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs

@@ -420,7 +420,7 @@ public static class StandardTrainersCatalog
        }

        /// <summary>
-        /// Predict a target using a linear binary classification model trained with <see cref="AveragedPerceptronTrainer"/> and advanced options.
+        /// Create an <see cref="AveragedPerceptronTrainer"/> with advanced options, which predicts a target using a linear binary classification model trained over boolean label data.


over boolean label data [](start = 160, length = 23)

over a label of boolean data. #Resolved

Natalie voted for no change.

In reply to: 275001284 [](ancestors = 275001284)

sfilipi · 2019-04-12T17:39:19Z

/// multiplied by a factor 0 &lt; a &lt;= 1, called the learning rate. In a generalization of this algorithm, the weights are updated by adding the feature vector multiplied by the learning rate,

no need to XML encode on md. YAY! :) #Resolved

Refers to: src/Microsoft.ML.StandardTrainers/Standard/Online/AveragedPerceptron.cs:53 in a9788b3. [](commit_id = a9788b3, deletion_comment = False)

sfilipi · 2019-04-12T17:41:21Z

src/Microsoft.ML.StandardTrainers/Standard/Online/AveragedPerceptron.cs

+    ///
+    /// [!include[io](~/../docs/samples/docs/api-reference/io-columns-binary-classification.md)]
+    ///
+    /// ### Trainer FAQ


Trainer [](start = 12, length = 7)

shall we call it estimator? #WontFix

sfilipi · 2019-04-12T17:41:40Z

src/Microsoft.ML.StandardTrainers/Standard/Online/AveragedPerceptron.cs

    /// </summary>
    /// <remarks>
+    /// <format type="text/markdown"><![CDATA[
+    /// To create this trainer, use [AveragedPerceptron](xref:Microsoft.ML.StandardTrainersCatalog.AveragedPerceptron(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,System.String,System.String,Microsoft.ML.Trainers.IClassificationLoss,System.Single,System.Boolean,System.Single,System.Int32)


trainer [](start = 23, length = 7)

estimator? #WontFix

natke

LGTM, aside from a couple of minor comments.

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs

natke · 2019-04-12T20:01:03Z

src/Microsoft.ML.StandardTrainers/Standard/Online/AveragedPerceptron.cs

+    ///
+    /// [!include[io](~/../docs/samples/docs/api-reference/io-columns-binary-classification.md)]
+    ///
+    /// ### Trainer FAQ


Agree that we should call it estimator.

And how about Features (instead of FAQ), so that would be "Estimator Features"? #WontFix

shmoradims · 2019-04-12T20:50:33Z

/// multiplied by a factor 0 &lt; a &lt;= 1, called the learning rate. In a generalization of this algorithm, the weights are updated by adding the feature vector multiplied by the learning rate,

changed.

In reply to: 482660867 [](ancestors = 482660867)

Refers to: src/Microsoft.ML.StandardTrainers/Standard/Online/AveragedPerceptron.cs:53 in a9788b3. [](commit_id = a9788b3, deletion_comment = False)

sfilipi · 2019-04-12T22:04:37Z

src/Microsoft.ML.StandardTrainers/Standard/Online/AveragedPerceptron.cs

+    /// | Machine learning task | Binary classification |
+    /// | Is normalization required? | Yes |
+    /// | Is caching required? | No |
+    /// | Additional required NuGet | None |


| Additional required NuGet | None [](start = 8, length = 35)

this line is the one I am debating on the other PR.

If we want to keep it, shall we at least have it in the format:

| NuGet | Microsoft.ML |

Someone landing in this page from a web search would be clueless about what is the additional.

sfilipi

wschin · 2019-04-15T16:26:41Z

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

@@ -0,0 +1,8 @@
+### Input and Output Columns


Looks the information below is not related to Input? Maybe you want to add the two types of inputs for binary classifiers --- single float column and multiple float columns (FFM).

the input information is the first line above the table about label. Because it doesn't have a fixed name (unlike output columns) it's just written in text.

FFM is a special binary classifier. For that we can add the multiple float input.

In reply to: 275443192 [](ancestors = 275443192)

wschin · 2019-04-15T16:28:31Z

src/Microsoft.ML.StandardTrainers/Standard/Online/AveragedPerceptron.cs

+    /// | Is caching required? | No |
+    /// | Additional required NuGet | None |
+    ///
+    /// ### Training Algorithm Details
    /// The perceptron is a classification algorithm that makes its predictions by finding a separating hyperplane.
    /// 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.
    /// That is the same as the sign of sigma[0, D-1] (w_i * f_i), where w_0, w_1,..., w_D-1 are the weights computed by the algorithm.


Suggested change

/// That is the same as the sign of sigma[0, D-1] (w_i * f_i), where w_0, w_1,..., w_D-1 are the weights computed by the algorithm.

/// That is the same as the sign of sigma[0, D-1] \sum_{i = 1}^n (w_i * f_i), where w_0, w_1,..., w_D-1 are the weights computed by the algorithm and n is the length of feature vector.

``` #Resolved

fixed

In reply to: 275443917 [](ancestors = 275443917)

wschin · 2019-04-15T21:58:00Z

src/Microsoft.ML.StandardTrainers/Standard/Online/AveragedPerceptron.cs

-    /// 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.
-    /// That is the same as the sign of sigma[0, D-1] (w_i * f_i), where w_0, w_1,..., w_D-1 are the weights computed by the algorithm.
+    /// 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.
+    /// 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.


Suggested change

/// 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.

/// 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_i$ is the i-th feature's coefficient computed by the algorithm.

) * Updated trainer docs for AveragedPerceptron * Addressed PR comments * Updated xref * Added more IO details. * Updated nuget statement * Fixed formula with latex syntax

Updated trainer docs for AveragedPerceptron

a9788b3

shmoradims requested review from natke, sfilipi, singlis and glibnub April 12, 2019 13:08

glibnub approved these changes Apr 12, 2019

View reviewed changes

sfilipi reviewed Apr 12, 2019

View reviewed changes

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs Show resolved Hide resolved

sfilipi reviewed Apr 12, 2019

View reviewed changes

natke approved these changes Apr 12, 2019

View reviewed changes

Addressed PR comments

e9b4c60

natke approved these changes Apr 12, 2019

View reviewed changes

Updated xref

059c761

sfilipi reviewed Apr 12, 2019

View reviewed changes

sfilipi approved these changes Apr 12, 2019

View reviewed changes

wschin reviewed Apr 15, 2019

View reviewed changes

Added more IO details.

810b809

shmoradims requested review from rogancarr and Ivanidzo4ka April 15, 2019 19:33

Shahab Moradi added 2 commits April 15, 2019 12:35

Updated nuget statement

8d0043e

Fixed formula with latex syntax

99790ee

wschin reviewed Apr 15, 2019

View reviewed changes

wschin approved these changes Apr 15, 2019

View reviewed changes

shmoradims merged commit 681c60e into dotnet:master Apr 15, 2019

shmoradims mentioned this pull request Apr 16, 2019

Docs and samples for the API reference site (P0 & P1 Trainers) #2522

Closed

ghost locked as resolved and limited conversation to collaborators Mar 22, 2022

	/// That is the same as the sign of sigma[0, D-1] (w_i * f_i), where w_0, w_1,..., w_D-1 are the weights computed by the algorithm.
	/// That is the same as the sign of sigma[0, D-1] \sum_{i = 1}^n (w_i * f_i), where w_0, w_1,..., w_D-1 are the weights computed by the algorithm and n is the length of feature vector.
	``` #Resolved

	/// 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.
	/// 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_i$ is the i-th feature's coefficient computed by the algorithm.

API reference - Updated trainer docs for AveragedPerceptron #3310

API reference - Updated trainer docs for AveragedPerceptron #3310

Uh oh!

Conversation

shmoradims commented Apr 12, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Apr 12, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

sfilipi Apr 12, 2019 • edited by shmoradims Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shmoradims Apr 12, 2019

Choose a reason for hiding this comment

Uh oh!

sfilipi Apr 12, 2019 • edited by shmoradims Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shmoradims Apr 12, 2019

Choose a reason for hiding this comment

Uh oh!

sfilipi commented Apr 12, 2019 • edited by shmoradims Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sfilipi Apr 12, 2019 • edited by shmoradims Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfilipi Apr 12, 2019 • edited by shmoradims Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

natke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

natke Apr 12, 2019 • edited by shmoradims Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shmoradims commented Apr 12, 2019

Uh oh!

sfilipi Apr 12, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfilipi left a comment

Choose a reason for hiding this comment

Uh oh!

wschin Apr 15, 2019

Choose a reason for hiding this comment

Uh oh!

shmoradims Apr 15, 2019

Choose a reason for hiding this comment

Uh oh!

wschin Apr 15, 2019 • edited by shmoradims Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shmoradims Apr 15, 2019

Choose a reason for hiding this comment

Uh oh!

wschin Apr 15, 2019

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shmoradims commented Apr 12, 2019 •

edited

Loading

codecov bot commented Apr 12, 2019 •

edited

Loading

sfilipi Apr 12, 2019 •

edited by shmoradims

Loading

sfilipi Apr 12, 2019 •

edited by shmoradims

Loading

sfilipi commented Apr 12, 2019 •

edited by shmoradims

Loading

sfilipi Apr 12, 2019 •

edited by shmoradims

Loading

sfilipi Apr 12, 2019 •

edited by shmoradims

Loading

natke Apr 12, 2019 •

edited by shmoradims

Loading

sfilipi Apr 12, 2019 •

edited

Loading

wschin Apr 15, 2019 •

edited by shmoradims

Loading