You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
/// Train a matrix factorization model. It factorizes the training matrix into the product of two low-rank matrices.
27
27
/// </summary>
28
28
/// <remarks>
29
-
/// <para>The basic idea of matrix factorization is finding two low-rank factor marcies to apporimate the training matrix.
30
-
/// In this module, the expected training data is a list of tuples. Every tuple consists of a column index, a row index,
29
+
/// <format type="text/markdown"><)
31
+
/// or [MatrixFactorization(Options)](xref:Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options)).
32
+
///
33
+
/// ### Input and Output Columns
34
+
/// 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 .
35
+
/// They together defines a matrix in [COO](https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_(COO)) format.
36
+
/// The type of label column is vector of <xref:System.Single> while the other two columns are key-typed scalar.
37
+
///
38
+
/// | Output Column Name | Column Type | Description|
39
+
/// | -- | -- | -- |
40
+
/// | `Score` | <xref:System.Single> | The predicted matrix value at the location specified by input columns (row index column and column index column). |
41
+
///
42
+
/// ### Trainer Characteristics
43
+
/// | | |
44
+
/// | -- | -- |
45
+
/// | Machine learning task | Recommender systems |
46
+
/// | Is normalization required? | Yes |
47
+
/// | Is caching required? | Yes |
48
+
/// | Required NuGet in addition to Microsoft.ML | Microsoft.ML.Recommender |
49
+
///
50
+
/// ### Background
51
+
/// The basic idea of matrix factorization is finding two low-rank factor marcies to apporimate the training matrix.
52
+
/// 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,
31
53
/// and the value at the location specified by the two indexes. For an example data structure of a tuple, one can use:
32
-
/// </para>
33
-
/// <code language="csharp">
54
+
///
55
+
/// ```csharp
34
56
/// // The following variables defines the shape of a m-by-n matrix. Indexes start with 0; that is, our indexing system
/// // The rating at the MatrixColumnIndex-th column and the MatrixRowIndex-th row.
49
71
/// public float Value;
50
72
/// }
51
-
/// </code>
52
-
/// <para> Notice that it's not necessary to specify all entries in the training matrix, so matrix factorization can be used to fill <i>missing values</i>.
53
-
/// This behavior is very helpful when building recommender systems.</para>
54
-
/// <para>To provide a better understanding on practical uses of matrix factorization, let's consider music recommendation as an example.
73
+
/// ```
74
+
///
75
+
/// Notice that it's not necessary to specify all entries in the training matrix, so matrix factorization can be used to fill <i>missing values</i>.
76
+
/// This behavior is very helpful when building recommender systems.
77
+
///
78
+
/// To provide a better understanding on practical uses of matrix factorization, let's consider music recommendation as an example.
55
79
/// Assume that user IDs and music IDs are used as row and column indexes, respectively, and matrix's values are ratings provided by those users. That is,
56
-
/// rating <i>r</i> at row <i>r</i> and column <i>v</i> means that user <i>u</i> give <i>r</i> to item <i>v</i>.
80
+
/// rating $r$ at row $u$ and column $v$ means that user $u$ give $r$ to item $v$.
57
81
/// An imcomplete matrix is very common because not all users may provide their feedbacks to all products (for example, no one can rate ten million songs).
58
-
/// Assume that<i>R</i> is a m-by-n rating matrix and the rank of the two factor matrices are<i>P</i> (m-by-k matrix) and <i>Q</i> (n-by-k matrix), where k is the approximation rank.
59
-
/// The predicted rating at the u-th row and the v-th column in <i>R</i> would be the inner product of the u-th row of P and the v-th row of Q; that is,
60
-
/// <i>R</i> is approximated by the product of <i>P</i>'s transpose and <i>Q</i>. This trainer implements
61
-
/// <a href='https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/mf_adaptive_pakdd.pdf'>a stochastic gradient method</a> for finding <i>P</i>
62
-
/// and <i>Q</i> via minimizing the distance between<i> R</i> and the product of <i>P</i>'s transpose and Q.</para>.
63
-
/// <para>The underlying library used in ML.NET matrix factorization can be found on <a href='https://github.com/cjlin1/libmf'>a Github repository</a>. For users interested in the mathematical details, please see the references below.</para>
64
-
/// <list type = 'bullet'>
65
-
/// <item>
66
-
/// <description><a href='https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/libmf_journal.pdf' > A Fast Parallel Stochastic Gradient Method for Matrix Factorization in Shared Memory Systems</a></description>
67
-
/// </item>
68
-
/// <item>
69
-
/// <description><a href='https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/mf_adaptive_pakdd.pdf' > A Learning-rate Schedule for Stochastic Gradient Methods to Matrix Factorization</a></description>
70
-
/// </item>
71
-
/// <item>
72
-
/// <description><a href='https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/libmf_open_source.pdf' > LIBMF: A Library for Parallel Matrix Factorization in Shared-memory Systems</a></description>
73
-
/// </item>
74
-
/// <item>
75
-
/// <description><a href='https://www.csie.ntu.edu.tw/~cjlin/papers/one-class-mf/biased-mf-sdm-with-supp.pdf' > Selection of Negative Samples for One-class Matrix Factorization</a></description>
/// 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.
83
+
/// 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$.
84
+
/// Note that $k$ is usually much smaller than $m$ and $n$, so $P^T Q$ is usually called a low-rank approximation of $R$.
85
+
///
86
+
/// 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$.
87
+
/// 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).
88
+
/// 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)
89
+
/// when calling [MatrixFactorization(Options)](xref:Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options)).
90
+
/// See Page 28 [here](https://www.csie.ntu.edu.tw/~cjlin/talks/facebook.pdf) for a brief introduction to one-class matrix factorization.
91
+
/// The default settting <see cref="MatrixFactorizationTrainer.LossFunctionType.SquareLossRegression"/> is for standard matrix factorization problem.
92
+
/// The underlying library used in ML.NET matrix factorization can be found on [a Github repository](https://github.com/cjlin1/libmf).
93
+
///
94
+
/// For users interested in the mathematical details, please see the references below.
95
+
///
96
+
/// * 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).
97
+
/// * 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).
98
+
/// * For the coordinate descent method used and one-class matrix factorization, see [Selection of Negative Samples for One-class Matrix Factorization](https://www.csie.ntu.edu.tw/~cjlin/papers/one-class-mf/biased-mf-sdm-with-supp.pdf).
99
+
/// * For details in the underlying library used, see [LIBMF: A Library for Parallel Matrix Factorization in Shared-memory Systems](https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/libmf_open_source.pdf).
/// Advanced options for the <see cref="MatrixFactorizationTrainer"/>.
133
+
/// Options for the <see cref="MatrixFactorizationTrainer"/> in [MatrixFactorization(Options)](xref:Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization(Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options)).
Copy file name to clipboardExpand all lines: src/Microsoft.ML.Recommender/RecommenderCatalog.cs
+2
Original file line number
Diff line number
Diff line change
@@ -80,6 +80,8 @@ public MatrixFactorizationTrainer MatrixFactorization(
80
80
/// <para>The basic idea of matrix factorization is finding two low-rank factor matrices to apporimate the training matrix.</para>
81
81
/// <para>In this module, the expected training data is a list of tuples. Every tuple consists of a column index, a row index,
82
82
/// and the value at the location specified by the two indexes. The training configuration is encoded in <see cref="MatrixFactorizationTrainer.Options"/>.
83
+
/// To invoke one-class matrix factorization, user needs to specify <see cref="MatrixFactorizationTrainer.LossFunctionType.SquareLossOneClass"/>.
84
+
/// The default settting <see cref="MatrixFactorizationTrainer.LossFunctionType.SquareLossRegression"/> is for standard matrix factorization problem.
83
85
/// </para>
84
86
/// </remarks>
85
87
/// <param name="options">Advanced arguments to the algorithm.</param>
0 commit comments