Documentation for Multiclass SDCA #3433

wschin · 2019-04-19T03:26:53Z

Toward #2522.

codemzs · 2019-04-19T22:34:03Z

Seems good just make sure the catalog extension methods are correctly documented such as "Create ..." and "Create with advanced options ..."

singlis · 2019-04-20T00:05:38Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    ///
+    /// | Output Column Name | Column Type | Description|
+    /// | -- | -- | -- |
+    /// | `Score` | array of<xref:System.Single> | The scores of all classes.Higher value means higher probability to fall into the associated class. If the i-th element has the lagest value, the predicted label index would be i.Note that i is zero-based index. |


minor - space between . and Higher #Resolved

singlis · 2019-04-20T00:05:51Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    ///
+    /// | Output Column Name | Column Type | Description|
+    /// | -- | -- | -- |
+    /// | `Score` | array of<xref:System.Single> | The scores of all classes.Higher value means higher probability to fall into the associated class. If the i-th element has the lagest value, the predicted label index would be i.Note that i is zero-based index. |


lagest [](start = 178, length = 6)

largest #Resolved

singlis · 2019-04-20T00:06:07Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    ///
+    /// | Output Column Name | Column Type | Description|
+    /// | -- | -- | -- |
+    /// | `Score` | array of<xref:System.Single> | The scores of all classes.Higher value means higher probability to fall into the associated class. If the i-th element has the lagest value, the predicted label index would be i.Note that i is zero-based index. |


another space after . #Resolved

singlis · 2019-04-20T00:08:55Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    /// The optimization algorithm is an extension of (http://jmlr.org/papers/volume14/shalev-shwartz13a/shalev-shwartz13a.pdf) following a similar path proposed in an earlier [paper](https://www.csie.ntu.edu.tw/~cjlin/papers/maxent_dual.pdf).
+    /// It is usually much faster than [L-BFGS](https://en.wikipedia.org/wiki/Limited-memory_BFGS) and [truncated Newton methods](https://en.wikipedia.org/wiki/Truncated_Newton_method) for large-scale and sparse data set.
+    ///
+    /// Regularization is a method that can render an ill-posed problem more tractable by imposing constraints that provide information to supplement the data and that prevents overfitting by penalizing model's magnitude usually measured by some norm functions.


norm [](start = 246, length = 4)

is it worth expanding norm functions to normalization functions? #Resolved

Nop. They are independent things. Norm is a name like sin/cos.

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

singlis

natke

These are my general recommendations after reviewing this PR and speaking with @wschin:

Describe any general properties of the algorithm in the base class.
Add documentation for each derived class (in the code comments of the derived class) that specifies:
- which output columns are produced (we should already have this)
- the interpretation of the output columns i.e. for SdcaMulticlass
  - SdcaMaximumEntropy
    - score column is a genuine probabililty
  - SdcaNonCalibrated
    - score column is a raw value (the highest value of which indicates the class)

natke · 2019-04-19T15:37:57Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    /// | Required NuGet in addition to Microsoft.ML | None |
+    ///
+    /// ### Scoring Function
+    /// This model trains linear model to solve multiclass classification problems.


trains a linear model #Resolved

natke · 2019-04-19T15:39:02Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    /// It assigns the $c$-th class a coefficient vector $\boldsymbol{w}_c \in {\mathbb R}^n$ and a bias $b_c \in {\mathbb R}$, for $c=1,\dots,m$.
+    /// Given a feature vector $\boldsymbol{x} \in {\mathbb R}^n$, the $c$-th class's score would be $\hat{y}^c = \boldsymbol{w}_c^T \boldsymbol{x} + b_c$.
+    ///
+    /// If and only if the trained model is maximum entropy classifier, user can interpret the output score vector as the predicted class probabilities because [softmax function](https://en.wikipedia.org/wiki/Softmax_function) may be applied to post-process all classes' scores.


is a maximum entropy classifier #Resolved

user --> you #Resolved

natke · 2019-04-19T15:39:57Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    /// It assigns the $c$-th class a coefficient vector $\boldsymbol{w}_c \in {\mathbb R}^n$ and a bias $b_c \in {\mathbb R}$, for $c=1,\dots,m$.
+    /// Given a feature vector $\boldsymbol{x} \in {\mathbb R}^n$, the $c$-th class's score would be $\hat{y}^c = \boldsymbol{w}_c^T \boldsymbol{x} + b_c$.
+    ///
+    /// If and only if the trained model is maximum entropy classifier, user can interpret the output score vector as the predicted class probabilities because [softmax function](https://en.wikipedia.org/wiki/Softmax_function) may be applied to post-process all classes' scores.


How do you interpret the score otherwise? #Resolved

Add

/// If $\boldsymbol{x}$ belongs to class $c$, then $\hat{y}^c$ should be much larger than 0. /// In contrast, a $\hat{y}^c$ much smaller than 0 means the desired label should not be $c$.

when explaining the scoring function.

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

natke · 2019-04-19T15:41:46Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    /// Regularization works by adding the penalty on the magnitude of $\boldsymbol{w}_c$, $c=1,\dots,m$ to the error of the hypothesis.
+    /// An accurate model with extreme coefficient values would be penalized more, but a less accurate model with more conservative values would be penalized less.
+    ///
+    /// This learner supports [elastic net regularization](https://en.wikipedia.org/wiki/Elastic_net_regularization): a linear combination of L1-norm (LASSO), $|| \boldsymbol{w}_c ||_1$, and L2-norm (ridge), $|| \boldsymbol{w}_c ||_2^2$ regularizations.


This learner --> this trainer or algorithm #Resolved

natke · 2019-04-19T15:42:58Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    /// | Required NuGet in addition to Microsoft.ML | None |
+    ///
+    /// ### Scoring Function
+    /// This model trains linear model to solve multiclass classification problems.


trains a linear model #Resolved

Thanks. Will fix another related API below.

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

natke · 2019-04-20T02:17:43Z

src/Microsoft.ML.StandardTrainers/Standard/SdcaMulticlass.cs

+    /// An accurate model with extreme coefficient values would be penalized more, but a less accurate model with more conservative values would be penalized less.
+    ///
+    /// This learner supports [elastic net regularization](https://en.wikipedia.org/wiki/Elastic_net_regularization): a linear combination of L1-norm (LASSO), $|| \boldsymbol{w}_c ||_1$, and L2-norm (ridge), $|| \boldsymbol{w}_c ||_2^2$ regularizations.
+    /// L1-nrom and L2-norm regularizations have different effects and uses that are complementary in certain respects.


nrom -> norm #Resolved

codecov · 2019-04-20T07:32:29Z

Codecov Report

❗ No coverage uploaded for pull request base (master@082ab77). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #3433   +/-   ##
=========================================
  Coverage          ?   72.76%           
=========================================
  Files             ?      808           
  Lines             ?   145452           
  Branches          ?    16244           
=========================================
  Hits              ?   105838           
  Misses            ?    35192           
  Partials          ?     4422

Flag	Coverage Δ
#Debug	`72.76% <ø> (?)`
#production	`68.27% <ø> (?)`
#test	`89.04% <ø> (?)`

Impacted Files	Coverage Δ
...oft.ML.StandardTrainers/StandardTrainersCatalog.cs	`92.34% <ø> (ø)`
...oft.ML.StandardTrainers/Standard/SdcaMulticlass.cs	`91.12% <ø> (ø)`

Documentation for Multiclass SDCA

5c88880

wschin added the documentation Related to documentation of ML.NET label Apr 19, 2019

wschin requested review from codemzs, artidoro and shmoradims April 19, 2019 03:26

wschin self-assigned this Apr 19, 2019

shmoradims mentioned this pull request Apr 19, 2019

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

Closed

wschin requested a review from natke April 19, 2019 15:23

codemzs approved these changes Apr 19, 2019

View reviewed changes

Fix cref

8c1d5aa

singlis reviewed Apr 20, 2019

View reviewed changes

Add types

dc02636

singlis approved these changes Apr 20, 2019

View reviewed changes

wschin added 2 commits April 19, 2019 17:18

Polish

524f33c

Fix typos

673b632

natke reviewed Apr 20, 2019

View reviewed changes

wschin added 2 commits April 19, 2019 23:06

Address comments

822ab5e

FIx

d3a5555

wschin merged commit 27b6cf3 into dotnet:master Apr 20, 2019

wschin deleted the mcsdca-doc branch April 20, 2019 07:24

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

Documentation for Multiclass SDCA #3433

Documentation for Multiclass SDCA #3433

Uh oh!

Conversation

wschin commented Apr 19, 2019

Uh oh!

codemzs commented Apr 19, 2019

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wschin Apr 20, 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!

singlis left a comment

Choose a reason for hiding this comment

Uh oh!

natke left a comment

Choose a reason for hiding this comment

Uh oh!

natke Apr 19, 2019 • edited by wschin 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 Apr 19, 2019 • edited by wschin 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 Apr 19, 2019 • edited by wschin 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 Apr 19, 2019 • edited by wschin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wschin Apr 20, 2019

Choose a reason for hiding this comment

Uh oh!

natke Apr 19, 2019 • edited by wschin 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 Apr 19, 2019 • edited by wschin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wschin Apr 20, 2019

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Uh oh!

singlis Apr 20, 2019 •

edited by wschin

Loading

singlis Apr 20, 2019 •

edited by wschin

Loading

singlis Apr 20, 2019 •

edited by wschin

Loading

singlis Apr 20, 2019 •

edited by wschin

Loading

wschin Apr 20, 2019 •

edited

Loading

natke Apr 19, 2019 •

edited by wschin

Loading

natke Apr 19, 2019 •

edited by wschin

Loading

natke Apr 19, 2019 •

edited by wschin

Loading

natke Apr 19, 2019 •

edited by wschin

Loading

natke Apr 19, 2019 •

edited by wschin

Loading

natke Apr 19, 2019 •

edited by wschin

Loading

natke Apr 20, 2019 •

edited by wschin

Loading

codecov bot commented Apr 20, 2019 •

edited

Loading