Updated xml docs for Poisson, OLS, and OGD regression trainers. #3059

shmoradims · 2019-03-21T23:46:44Z

Related to #2522

codecov · 2019-03-22T00:25:13Z

Codecov Report

Merging #3059 into master will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #3059      +/-   ##
==========================================
+ Coverage   72.51%   72.52%   +0.01%     
==========================================
  Files         804      805       +1     
  Lines      144150   144243      +93     
  Branches    16179    16175       -4     
==========================================
+ Hits       104524   104614      +90     
- Misses      35216    35226      +10     
+ Partials     4410     4403       -7

Flag	Coverage Δ
#Debug	`72.52% <ø> (+0.01%)`	⬆️
#production	`68.14% <ø> (ø)`	⬆️
#test	`88.76% <ø> (+0.02%)`	⬆️

Impacted Files	Coverage Δ
...Microsoft.ML.Mkl.Components/OlsLinearRegression.cs	`66.3% <ø> (ø)`	⬆️
...icrosoft.ML.Mkl.Components/MklComponentsCatalog.cs	`65.71% <ø> (ø)`	⬆️
...L.StandardTrainers/Standard/Online/OnlineLinear.cs	`79.43% <ø> (ø)`	⬆️
...StandardTrainers/Standard/Online/AveragedLinear.cs	`59.5% <ø> (ø)`	⬆️
...dTrainers/Standard/Online/OnlineGradientDescent.cs	`92.3% <ø> (ø)`	⬆️
.../Standard/LogisticRegression/LbfgsPredictorBase.cs	`71.26% <ø> (ø)`	⬆️
...rs/Standard/PoissonRegression/PoissonRegression.cs	`88.57% <ø> (ø)`	⬆️
...oft.ML.StandardTrainers/StandardTrainersCatalog.cs	`89.07% <ø> (ø)`	⬆️
.../Microsoft.ML.Data/Model/ModelOperationsCatalog.cs	`91.73% <0%> (-5.54%)`	⬇️
src/Microsoft.ML.Transforms/Text/LdaTransform.cs	`89.26% <0%> (-0.63%)`	⬇️
... and 14 more

sfilipi · 2019-03-22T04:58:32Z

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs


        /// <summary>
-        /// Predict a target using a linear regression model trained with the <see cref="OnlineGradientDescentTrainer"/> trainer.
+        /// Predict a target using a linear regression model trained with the <see cref="OnlineGradientDescentTrainer"/> and advanced options.


and [](start = 121, length = 3)

specifying #WontFix

i think "and" is good enough and reads well. This is the language pattern I've used for all trainers so far, so I don't want to make recursive changes to completed trainers unless there's an error or major improvement.

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

sfilipi · 2019-03-22T04:59:04Z

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs

        /// <param name="l2Regularization">The L2 weight for <a href='tmpurl_regularization'>regularization</a>.</param>
        /// <param name="optimizationTolerance">Threshold for optimizer convergence.</param>
-        /// <param name="historySize">Memory size for <see cref="Microsoft.ML.Trainers.PoissonRegressionTrainer"/>. Low=faster, less accurate.</param>
+        /// <param name="historySize">Number of previous iterations to remember for estimate of Hessian. Lower values mean faster but less accurate estimates.</param>


for estima [](start = 80, length = 10)

for the estimate of the Hessian. #Resolved

done

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

sfilipi · 2019-03-22T04:59:25Z

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs


        /// <summary>
-        /// Predict a target using a linear regression model trained with the <see cref="Microsoft.ML.Trainers.PoissonRegressionTrainer"/> trainer.
+        /// Predict a target using a linear regression model trained with the <see cref="Microsoft.ML.Trainers.PoissonRegressionTrainer"/> and advanced options.


and [](start = 139, length = 3)

specifying #Resolved

same as before

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

sfilipi · 2019-03-22T04:59:53Z

src/Microsoft.ML.StandardTrainers/Standard/LogisticRegression/LbfgsPredictorBase.cs


            /// <summary>
-            /// Number of previous iterations to remember for estimate of Hessian.
+            /// Number of previous iterations to remember for estimate of Hessian. Lower values mean faster but less accurate estimates.


for estimate of Hessian [](start = 57, length = 24)

ditto #Resolved

done

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

sfilipi · 2019-03-22T05:01:29Z

src/Microsoft.ML.StandardTrainers/Standard/LogisticRegression/LbfgsPredictorBase.cs


            /// <summary>
-            /// Features must occur in at least this many instances to be included
+            /// Determines whether to produce output during training or not.


Determines whether to produce output during training or not. [](start = 16, length = 60)

should it be more explicit: If set to true produces no output during training.

Users can imply the correct usage from the parameter name, but why leave it to implying. #Resolved

added

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

sfilipi · 2019-03-22T05:01:54Z

src/Microsoft.ML.StandardTrainers/Standard/LogisticRegression/LbfgsPredictorBase.cs

+            /// Determines whether to produce output during training or not.
            /// </summary>
-            /// <remarks>If greater than 1, forces an initialization pass over the data</remarks>
-            //AP removed from now. This requires data transformatio. Perhaps we should handle it as seprate (non-learner) dependant


shall we keep this piece of info? I bet one = true. #Resolved

diff is not showing well here. The removed text is for CountThreshold which is commented out and I removed it.

This has been dead argument for about a year. If it's important, it can be dug out of git history later on. For now we should clean it up.

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

sfilipi · 2019-03-22T05:03:28Z

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

-    /// <include file='doc.xml' path='doc/members/member[@name="OGD"]/*' />
+    /// <summary>
+    /// The <see cref="IEstimator{TTransformer}"/> for training a linear regression model using
+    /// online gradient descent (OGD) for estimating the parameters of the linear regression model.


online gradient descent [](start = 7, length = 24)

feel like those are usually capitalized.

see here: https://papers.nips.cc/paper/3319-adaptive-online-gradient-descent.pdf #Resolved

You're looking at Title Case in the paper. There are all-lowercase instances in that same paper. But I changed it anyways.

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

sfilipi · 2019-03-22T05:04:16Z

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

            internal ISupportRegressionLossFactory RegressionLossFunctionFactory = new SquaredLossFactory();

+            /// <summary>
+            /// A custom <a href="tmpurl_loss">loss</a>.


tmpurl_loss [](start = 34, length = 11)

should probably fix those before V1 #Resolved

in April

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

sfilipi

rogancarr · 2019-03-22T18:41:33Z

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs

        /// <summary>
-        /// Predict a target using a linear regression model trained with the <see cref="Microsoft.ML.Trainers.PoissonRegressionTrainer"/> trainer.
+        /// Predict a target using a linear regression model trained with the <see cref="Microsoft.ML.Trainers.PoissonRegressionTrainer"/>.
        /// </summary>


[](start = 12, length = 10)

Can you please add a remarks section with a discussion of what Poisson regression is? We've had users who are trying to use this for plain linear regression, and this is a bit specialized. #Resolved

Oh, nevermind -- I see you did this is the base trainer.

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

rogancarr

Updated xml docs for Poisson, OLS, and OGD regression trainers.

284f6d5

shmoradims requested review from rogancarr, sfilipi and zeahmed March 21, 2019 23:46

sfilipi reviewed Mar 22, 2019

View reviewed changes

sfilipi approved these changes Mar 22, 2019

View reviewed changes

Addressed PR comments.

fa5255d

shmoradims requested a review from singlis March 22, 2019 18:21

shmoradims mentioned this pull request Mar 22, 2019

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

Closed

rogancarr reviewed Mar 22, 2019

View reviewed changes

rogancarr approved these changes Mar 22, 2019

View reviewed changes

shmoradims merged commit b241bcd into dotnet:master Mar 22, 2019

shmoradims deleted the docs_regression_trainers2 branch April 2, 2019 23:41

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

Updated xml docs for Poisson, OLS, and OGD regression trainers. #3059

Updated xml docs for Poisson, OLS, and OGD regression trainers. #3059

Uh oh!

Conversation

shmoradims commented Mar 21, 2019

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

sfilipi Mar 22, 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!

Choose a reason for hiding this comment

Uh oh!

sfilipi Mar 22, 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!

Choose a reason for hiding this comment

Uh oh!

sfilipi Mar 22, 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!

Choose a reason for hiding this comment

Uh oh!

sfilipi Mar 22, 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!

Choose a reason for hiding this comment

Uh oh!

sfilipi Mar 22, 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!

Choose a reason for hiding this comment

Uh oh!

sfilipi Mar 22, 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 Mar 22, 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 Mar 22, 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!

Choose a reason for hiding this comment

Uh oh!

sfilipi Mar 22, 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!

Choose a reason for hiding this comment

Uh oh!

sfilipi left a comment

Choose a reason for hiding this comment

Uh oh!

rogancarr Mar 22, 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!

Choose a reason for hiding this comment

Uh oh!

rogancarr left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Mar 22, 2019 •

edited

Loading

sfilipi Mar 22, 2019 •

edited by shmoradims

Loading

sfilipi Mar 22, 2019 •

edited by shmoradims

Loading

sfilipi Mar 22, 2019 •

edited by shmoradims

Loading

sfilipi Mar 22, 2019 •

edited by shmoradims

Loading

sfilipi Mar 22, 2019 •

edited by shmoradims

Loading

sfilipi Mar 22, 2019 •

edited by shmoradims

Loading

shmoradims Mar 22, 2019 •

edited

Loading

sfilipi Mar 22, 2019 •

edited by shmoradims

Loading

sfilipi Mar 22, 2019 •

edited by shmoradims

Loading

rogancarr Mar 22, 2019 •

edited

Loading