-
Notifications
You must be signed in to change notification settings - Fork 1.9k
Matrix Factorization XML docs #3409
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Codecov Report
@@ Coverage Diff @@
## master #3409 +/- ##
==========================================
+ Coverage 72.69% 72.74% +0.04%
==========================================
Files 807 807
Lines 145171 145206 +35
Branches 16225 16230 +5
==========================================
+ Hits 105536 105632 +96
+ Misses 35220 35153 -67
- Partials 4415 4421 +6
|
/// or [MatrixFactorization(Options)](xref:Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options)). | ||
/// | ||
/// ### Input and Output Columns | ||
/// There are three input columns required, one for matrix row indexes, one for matrix column indexes, and one for values (i.e., labels) in matrix . |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[](start = 150, length = 1)
extra space. #Resolved
/// | ||
/// ### Input and Output Columns | ||
/// There are three input columns required, one for matrix row indexes, one for matrix column indexes, and one for values (i.e., labels) in matrix . | ||
/// They together defines a matrix in [COO](https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_(COO)) format. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
defines [](start = 22, length = 7)
define a matrix #Resolved
/// ### Input and Output Columns | ||
/// There are three input columns required, one for matrix row indexes, one for matrix column indexes, and one for values (i.e., labels) in matrix . | ||
/// They together defines a matrix in [COO](https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_(COO)) format. | ||
/// The type of label column is vector of <xref:System.Single> while the other two columns are key-typed scalar. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The type of label column is vector of xref:System.Single [](start = 8, length = 58)
suggested: The type for label column is a vector of xref:System.Single ... #Resolved
/// ### Input and Output Columns | ||
/// There are three input columns required, one for matrix row indexes, one for matrix column indexes, and one for values (i.e., labels) in matrix . | ||
/// They together defines a matrix in [COO](https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_(COO)) format. | ||
/// The type of label column is vector of <xref:System.Single> while the other two columns are key-typed scalar. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
key-typed scalar [](start = 99, length = 16)
Key-typed scalar? What does that mean? Are you talking about KeyType? Should this have an xref? #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will do [key-typed](<xref:Microsoft.ML.Data.KeyDataViewType>) scalar
In reply to: 276858813 [](ancestors = 276858813)
/// | Required NuGet in addition to Microsoft.ML | Microsoft.ML.Recommender | | ||
/// | ||
/// ### Background | ||
/// The basic idea of matrix factorization is finding two low-rank factor marcies to apporimate the training matrix. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
marcies [](start = 78, length = 7)
matrices? #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// | Required NuGet in addition to Microsoft.ML | Microsoft.ML.Recommender | | ||
/// | ||
/// ### Background | ||
/// The basic idea of matrix factorization is finding two low-rank factor marcies to apporimate the training matrix. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
apporimate [](start = 89, length = 10)
approximate? #Resolved
/// | ||
/// ### Background | ||
/// The basic idea of matrix factorization is finding two low-rank factor marcies to apporimate the training matrix. | ||
/// In this module, the expected training data, the factorized matrix, is a list of tuples. Every tuple consists of a column index, a row index, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
, [](start = 50, length = 1)
suggestion: the expected training data and the factorized matrix is a list of tuples. #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will do the expected training data (the factorized matrix) is a list of tuples
because training data = factorized matrix.
In reply to: 276859310 [](ancestors = 276859310)
/// | ||
/// ### Background | ||
/// The basic idea of matrix factorization is finding two low-rank factor marcies to apporimate the training matrix. | ||
/// In this module, the expected training data, the factorized matrix, is a list of tuples. Every tuple consists of a column index, a row index, | ||
/// and the value at the location specified by the two indexes. For an example data structure of a tuple, one can use: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
indexes [](start = 59, length = 7)
indices? #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// <] | ||
/// Assume that $R\in{\mathbb R}^{m\times n}$ is a m-by-n rating matrix and the [rank](https://en.wikipedia.org/wiki/Rank_(linear_algebra)) of the two factor matrices are $P\in {\mathbb R}^{k\times m}$ and $Q\in {\mathbb R}^{k\times n}$, where $k$ is the approximation rank. | ||
/// The predicted rating at the $u$-th row and the $v$-th column in $R$ would be the inner product of the $u$-th row of P and the $v$-th row of Q; that is, $R$ is approximated by the product of $P$'s transpose ($P^T$) and $Q$. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
$R$ [](start = 72, length = 3)
R is referenced in latex, but P and Q are not. #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// The predicted rating at the $u$-th row and the $v$-th column in $R$ would be the inner product of the $u$-th row of P and the $v$-th row of Q; that is, $R$ is approximated by the product of $P$'s transpose ($P^T$) and $Q$. | ||
/// Note that $k$ is usually much smaller than $m$ and $n$, so $P^T Q$ is usually called a low-rank approximation of $R$. | ||
/// | ||
/// This trainer includes a [stochastic gradient method](https://en.wikipedia.org/wiki/Stochastic_gradient_descent) and [a coordinate descent method](https://en.wikipedia.org/wiki/Coordinate_descent) for finding $P$ and $Q$ via minimizing the distance between (non-missing part of) $R$ and its approximation $P^T Q$. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
a [](start = 125, length = 1)
minor, should 'a' be part of the uri? #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// | ||
/// This trainer includes a [stochastic gradient method](https://en.wikipedia.org/wiki/Stochastic_gradient_descent) and [a coordinate descent method](https://en.wikipedia.org/wiki/Coordinate_descent) for finding $P$ and $Q$ via minimizing the distance between (non-missing part of) $R$ and its approximation $P^T Q$. | ||
/// The coordinate descent method included is specifically for one-class matrix factorization where all observed ratings are positive signals (that is, all rating values are 1). | ||
/// Notice taht the only way to invoke one-class matrix factorization is to assign <see cref="Microsoft.ML.Trainers.MatrixFactorizationTrainer.LossFunctionType.SquareLossOneClass"/> to [loss function](Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options.LossFunction) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cref [](start = 92, length = 4)
cref in markdown?? who does that? :) #Resolved
/// | ||
/// This trainer includes a [stochastic gradient method](https://en.wikipedia.org/wiki/Stochastic_gradient_descent) and [a coordinate descent method](https://en.wikipedia.org/wiki/Coordinate_descent) for finding $P$ and $Q$ via minimizing the distance between (non-missing part of) $R$ and its approximation $P^T Q$. | ||
/// The coordinate descent method included is specifically for one-class matrix factorization where all observed ratings are positive signals (that is, all rating values are 1). | ||
/// Notice taht the only way to invoke one-class matrix factorization is to assign <see cref="Microsoft.ML.Trainers.MatrixFactorizationTrainer.LossFunctionType.SquareLossOneClass"/> to [loss function](Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options.LossFunction) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
taht [](start = 15, length = 4)
that #Resolved
/// Notice taht the only way to invoke one-class matrix factorization is to assign <see cref="Microsoft.ML.Trainers.MatrixFactorizationTrainer.LossFunctionType.SquareLossOneClass"/> to [loss function](Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options.LossFunction) | ||
/// when calling [MatrixFactorization(Options)](xref:Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options)). | ||
/// See Page 28 [here](https://www.csie.ntu.edu.tw/~cjlin/talks/facebook.pdf) for a brief introduction to one-class matrix factorization. | ||
/// The default settting <see cref="MatrixFactorizationTrainer.LossFunctionType.SquareLossRegression"/> is for standard matrix factorization problem. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cref [](start = 34, length = 4)
another cref #Resolved
/// For users interested in the mathematical details, please see the references below. | ||
/// | ||
/// * For the multi-threading implementation of the used stochastic gradient method, see [A Fast Parallel Stochastic Gradient Method for Matrix Factorization in Shared Memory Systems](https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/libmf_journal.pdf). | ||
/// * For the computation happened inside one thread, see [A Learning-rate Schedule for Stochastic Gradient Methods to Matrix Factorization](https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/mf_adaptive_pakdd.pdf). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
happened [](start = 30, length = 8)
happening inside a single thread? #Resolved
/// </remarks> | ||
/// <seealso cref="Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(System.String,System.String,System.String,System.Int32,System.Double,System.Int32)"/> | ||
/// <seealso cref="Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options)"/> | ||
/// <seealso cref="Options"/> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Options [](start = 23, length = 7)
is this one needed? #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@@ -80,6 +80,8 @@ internal RecommendationTrainers(RecommendationCatalog catalog) | |||
/// <para>The basic idea of matrix factorization is finding two low-rank factor matrices to apporimate the training matrix.</para> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
apporimate [](start = 104, length = 10)
approximate #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
please add spell-checker plugin, if you haven't already
https://marketplace.visualstudio.com/items?itemName=EWoodruff.VisualStudioSpellChecker
In reply to: 276862518 [](ancestors = 276862518)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@@ -80,6 +80,8 @@ internal RecommendationTrainers(RecommendationCatalog catalog) | |||
/// <para>The basic idea of matrix factorization is finding two low-rank factor matrices to apporimate the training matrix.</para> | |||
/// <para>In this module, the expected training data is a list of tuples. Every tuple consists of a column index, a row index, | |||
/// and the value at the location specified by the two indexes. The training configuration is encoded in <see cref="MatrixFactorizationTrainer.Options"/>. | |||
/// To invoke one-class matrix factorization, user needs to specify <see cref="MatrixFactorizationTrainer.LossFunctionType.SquareLossOneClass"/>. | |||
/// The default settting <see cref="MatrixFactorizationTrainer.LossFunctionType.SquareLossRegression"/> is for standard matrix factorization problem. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we're moving all the algo-details remarks to the estimator class. you can just link there instead of repeating the content. #ByDesign
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe no because 1) this thing I have explained to an user 3 times on Gitter 2) this is the switch of implicit-feedback and explicit-feed recommendation --- a formula change rather than an algorithm change.
In reply to: 276869690 [](ancestors = 276869690)
@@ -80,6 +80,8 @@ internal RecommendationTrainers(RecommendationCatalog catalog) | |||
/// <para>The basic idea of matrix factorization is finding two low-rank factor matrices to apporimate the training matrix.</para> | |||
/// <para>In this module, the expected training data is a list of tuples. Every tuple consists of a column index, a row index, | |||
/// and the value at the location specified by the two indexes. The training configuration is encoded in <see cref="MatrixFactorizationTrainer.Options"/>. | |||
/// To invoke one-class matrix factorization, user needs to specify <see cref="MatrixFactorizationTrainer.LossFunctionType.SquareLossOneClass"/>. | |||
/// The default settting <see cref="MatrixFactorizationTrainer.LossFunctionType.SquareLossRegression"/> is for standard matrix factorization problem. | |||
/// </para> | |||
/// </remarks> | |||
/// <param name="options">Advanced arguments to the algorithm.</param> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Advanced arguments to the algorithm. [](start = 38, length = 36)
"Trainer options." is the current template. #Resolved
@@ -26,11 +26,33 @@ namespace Microsoft.ML.Trainers | |||
/// Train a matrix factorization model. It factorizes the training matrix into the product of two low-rank matrices. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// Train a matr [](start = 4, length = 16)
please follow template #Resolved
/// ]]> | ||
/// </format> | ||
/// </example> | ||
/// </remarks> | ||
/// <seealso cref="Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(System.String,System.String,System.String,System.Int32,System.Double,System.Int32)"/> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
System.String [](start = 101, length = 13)
no need to change these to fully qualified names. cref is more forgiving. whatever link visual studio intellisense gives you should be good. #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just want to reuse my xref. I could easily make mistake when modifying those things.
In reply to: 276870656 [](ancestors = 276870656)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
intellisense will do the work for you. I'm not even certain xref-UID would work with cref.
please change as we discussed on Teams.
In reply to: 277024650 [](ancestors = 277024650,276870656)
@@ -109,22 +134,25 @@ public enum LossFunctionType | |||
}; | |||
|
|||
/// <summary> | |||
/// Advanced options for the <see cref="MatrixFactorizationTrainer"/>. | |||
/// Options for the <see cref="MatrixFactorizationTrainer"/> in [MatrixFactorization(Options)](xref:Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options)). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
in [](start = 69, length = 2)
as used in #Resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Toward #2522 following #3218.