Skip to content

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

Merged
merged 5 commits into from
Apr 20, 2019
Merged

Matrix Factorization XML docs #3409

merged 5 commits into from
Apr 20, 2019

Conversation

wschin
Copy link
Member

@wschin wschin commented Apr 18, 2019

Toward #2522 following #3218.

@wschin wschin added the documentation Related to documentation of ML.NET label Apr 18, 2019
@wschin wschin requested review from Ivanidzo4ka and sfilipi April 18, 2019 20:42
@wschin wschin self-assigned this Apr 18, 2019
@codecov
Copy link

codecov bot commented Apr 18, 2019

Codecov Report

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

@@            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
Flag Coverage Δ
#Debug 72.74% <ø> (+0.04%) ⬆️
#production 68.29% <ø> (+0.06%) ⬆️
#test 88.98% <ø> (ø) ⬆️
Impacted Files Coverage Δ
...osoft.ML.Recommender/MatrixFactorizationTrainer.cs 70.39% <ø> (ø) ⬆️
src/Microsoft.ML.Recommender/RecommenderCatalog.cs 70.83% <ø> (ø) ⬆️
src/Microsoft.ML.Data/Transforms/KeyToValue.cs 79.16% <0%> (-0.65%) ⬇️
src/Microsoft.ML.Transforms/Text/LdaTransform.cs 89.26% <0%> (-0.63%) ⬇️
...ML.Transforms/MutualInformationFeatureSelection.cs 78.58% <0%> (-0.33%) ⬇️
...ML.Data/Transforms/ColumnConcatenatingEstimator.cs 80.3% <0%> (ø) ⬆️
...soft.ML.Transforms/Text/WordEmbeddingsExtractor.cs 87.52% <0%> (ø) ⬆️
...icrosoft.ML.FastTree/RandomForestClassification.cs 78.07% <0%> (ø) ⬆️
...forms/FeatureContributionCalculationTransformer.cs 73.55% <0%> (ø) ⬆️
...soft.ML.Tests/Transformers/CategoricalHashTests.cs 100% <0%> (ø) ⬆️
... and 42 more

/// 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 .
Copy link
Member

@singlis singlis Apr 18, 2019

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.
Copy link
Member

@singlis singlis Apr 18, 2019

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.
Copy link
Member

@singlis singlis Apr 18, 2019

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.
Copy link
Member

@singlis singlis Apr 18, 2019

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

Copy link
Member Author

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.
Copy link
Member

@singlis singlis Apr 18, 2019

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes!


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

/// | 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.
Copy link
Member

@singlis singlis Apr 18, 2019

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,
Copy link
Member

@singlis singlis Apr 18, 2019

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

Copy link
Member Author

@wschin wschin Apr 19, 2019

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:
Copy link
Member

@singlis singlis Apr 18, 2019

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok.


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

/// <![CDATA[
/// [!code-csharp[MF](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Recommendation/MatrixFactorization.cs)]
/// 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$.
Copy link
Member

@singlis singlis Apr 18, 2019

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catch!


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

/// 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$.
Copy link
Member

@singlis singlis Apr 18, 2019

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It shouldn't. CD is a family of algorithms.


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

///
/// 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)
Copy link
Member

@singlis singlis Apr 18, 2019

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)
Copy link
Member

@singlis singlis Apr 18, 2019

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.
Copy link
Member

@singlis singlis Apr 18, 2019

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).
Copy link
Member

@singlis singlis Apr 18, 2019

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"/>
Copy link
Member

@singlis singlis Apr 18, 2019

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes


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

@@ -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>
Copy link
Member

@singlis singlis Apr 18, 2019

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

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)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Super helpful tip. Thanks.


In reply to: 276869057 [](ancestors = 276869057,276862518)

Copy link
Member

@singlis singlis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:shipit:

@@ -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.
Copy link

@shmoradims shmoradims Apr 18, 2019

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

Copy link
Member Author

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>
Copy link

@shmoradims shmoradims Apr 18, 2019

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

@shmoradims
Copy link

shmoradims commented Apr 18, 2019

        /// Train a matrix factorization model. It factorizes the training matrix into the product of two low-rank matrices.

please follow template #Resolved


Refers to: src/Microsoft.ML.Recommender/RecommenderCatalog.cs:77 in 000aa46. [](commit_id = 000aa46, deletion_comment = False)

@shmoradims
Copy link

shmoradims commented Apr 18, 2019

        /// Train a matrix factorization model. It factorizes the training matrix into the product of two low-rank matrices.

same here #Resolved


Refers to: src/Microsoft.ML.Recommender/RecommenderCatalog.cs:46 in 000aa46. [](commit_id = 000aa46, deletion_comment = False)

@shmoradims
Copy link

shmoradims commented Apr 18, 2019

        /// <param name="matrixColumnIndexColumnName">The name of the column hosting the matrix's column IDs.</param>

is there any data type information here? #Resolved


Refers to: src/Microsoft.ML.Recommender/RecommenderCatalog.cs:55 in 000aa46. [](commit_id = 000aa46, deletion_comment = False)

@@ -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.
Copy link

@shmoradims shmoradims Apr 18, 2019

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)"/>
Copy link

@shmoradims shmoradims Apr 18, 2019

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

Copy link
Member Author

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)

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)

@wschin wschin requested a review from natke April 19, 2019 15:23
@wschin wschin requested a review from shmoradims April 19, 2019 16:30
@@ -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)).
Copy link

@shmoradims shmoradims Apr 19, 2019

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

Copy link

@shmoradims shmoradims left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:shipit:

@wschin wschin merged commit 3fa207d into dotnet:master Apr 20, 2019
@wschin wschin deleted the xml-mf branch April 20, 2019 03:55
@ghost ghost locked as resolved and limited conversation to collaborators Mar 22, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
documentation Related to documentation of ML.NET
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants