Add user guide #690
Open
Add user guide #690
+121
−1
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
for more information, see https://pre-commit.ci
…nto add/user_guide
MUCDK
reviewed
May 6, 2024
MUCDK
reviewed
May 6, 2024
MUCDK
reviewed
May 6, 2024
MUCDK
requested changes
May 6, 2024
|
missing:
|
MUCDK
reviewed
May 14, 2024
MUCDK
reviewed
May 14, 2024
MUCDK
reviewed
May 14, 2024
MUCDK
reviewed
May 14, 2024
|
Please also add a general reference to examples / tutorials at the end. |
MUCDK
reviewed
May 29, 2024
|
|
||
| In their original formulation, OT algorithms don't scale to large datasets due to their high computational complexity. Moscot overcomes this limitation by allowing for the use of low-rank solvers. In each `solve` method we have the `rank` parameter, by default $-1$ -- the full rank. | ||
| Whenever possible, it's best to start with the full rank, but when needed, the rank should be set to a positive integer. The higher the rank, the better the full-rank approximation. Hence, one should start with a reasonable high rank, e.g. $5000$. Consecutively decrease the rank if needed due to memory constraints. Note that the scale of $\tau_a$ and $\tau_b$ changes whenever we are in the low-rank setting. While they should be still between $0$ and $1$, empirically they should be set in the range between $0.1$ and $0.5$. See {doc}`/notebooks/examples/solvers/100_linear_problems_basic` and {doc}`/notebooks/examples/solvers/300_quad_problems_basic` on how to use low-rank solutions. | ||
| Another option to use the full rank is to specify the `batch_size` parameter of the `solve` method. It determines the number of rows or columns of the cost matrix to materialize during the {term}`Sinkhorn` iterations. Larger values will require more memory and can be adjusted due to memory constraints as well. |
There was a problem hiding this comment.
Can we have this before low-rank? and then say, for linear problems we can do the batch_size, which reduces memory complexity (but slightly increase time complexity).
and then we motivate the low-rank: Whenever time complexity in a linear problem (e.g. TemporalProblem) should be reduced, or memory/time complexity in a quadratic (enumarte / link quadratic problems here) problem should be reduced , we use low-rank OT.
MUCDK
reviewed
May 29, 2024
|
|
||
| ## Hyperparameters | ||
|
|
||
| Moscot problems' `solve` methods have the following parameters that can be set depending on the specific task: |
There was a problem hiding this comment.
The solve method of moscot problems have a wide range of parameters. In the following, we discuss the most relevant ones:
MUCDK
reviewed
May 29, 2024
|
|
||
| Moscot problems' `solve` methods have the following parameters that can be set depending on the specific task: | ||
|
|
||
| - $\varepsilon$ - {term}`Entropic regularization`. |
There was a problem hiding this comment.
[...] This determines the stochasticity of the map. The higher epsilon, the more stochastic the map is.
MUCDK
reviewed
May 29, 2024
| Moscot problems' `solve` methods have the following parameters that can be set depending on the specific task: | ||
|
|
||
| - $\varepsilon$ - {term}`Entropic regularization`. | ||
| - $\tau_a$ and $\tau_b$ - Parameters in $(0, 1]$ that define how {term}`unbalanced <unbalanced OT problem>` is the problem on the source and target {term}`marginals`. If $1$, the problem is {term}`balanced <balanced OT problem>`. |
There was a problem hiding this comment.
The lower tau, the more "unbalanced" the problem. Unbalancedness allows to automatically discard outliers, compensate for undesired distributional shifts, and model cell proliferation and apoptosis.
MUCDK
reviewed
May 29, 2024
|
|
||
| - $\varepsilon$ - {term}`Entropic regularization`. | ||
| - $\tau_a$ and $\tau_b$ - Parameters in $(0, 1]$ that define how {term}`unbalanced <unbalanced OT problem>` is the problem on the source and target {term}`marginals`. If $1$, the problem is {term}`balanced <balanced OT problem>`. | ||
| - $\alpha$ - Parameter in $(0, 1]$ that interpolates between the {term}`quadratic term` and the {term}`linear term`. $\alpha = 1$ corresponds to the pure {term}`Gromov-Wasserstein` problem while $\alpha \to 0$ corresponds to the pure {term}`linear problem`. |
There was a problem hiding this comment.
... Fused Gromov-Wasserstein).....
MUCDK
reviewed
May 29, 2024
| - $\varepsilon$ - {term}`Entropic regularization`. | ||
| - $\tau_a$ and $\tau_b$ - Parameters in $(0, 1]$ that define how {term}`unbalanced <unbalanced OT problem>` is the problem on the source and target {term}`marginals`. If $1$, the problem is {term}`balanced <balanced OT problem>`. | ||
| - $\alpha$ - Parameter in $(0, 1]$ that interpolates between the {term}`quadratic term` and the {term}`linear term`. $\alpha = 1$ corresponds to the pure {term}`Gromov-Wasserstein` problem while $\alpha \to 0$ corresponds to the pure {term}`linear problem`. | ||
| - `batch_size` - Number of rows/columns of the cost matrix to materialize during the solver iterations. Larger value will require more memory. |
There was a problem hiding this comment.
....See above the scalability
MUCDK
reviewed
May 29, 2024
| - `batch_size` - Number of rows/columns of the cost matrix to materialize during the solver iterations. Larger value will require more memory. | ||
| - `rank` - Rank of the {term}`low-rank OT` solver {cite}`scetbon:21b`. If $-1$, full-rank solver {cite}`peyre:2016` is used. | ||
|
|
||
| For more hyperparameters and their usage please refer to {doc}`/notebooks/examples/solvers/200_linear_problems_advanced` and {doc}`/notebooks/examples/solvers/400_quad_problems_advanced`. |
There was a problem hiding this comment.
you should also link to basic solve examples.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.