Skip to content

[MRG] Clarify transported mass in partial OT - #902

Merged
rflamary merged 5 commits into
PythonOT:masterfrom
JaylenTang:docs-partial-ot-mass-review
Nov 17, 2026
Merged

rflamary merged 5 commits into
PythonOT:masterfrom
JaylenTang:docs-partial-ot-mass-review

Conversation

@JaylenTang

@JaylenTang JaylenTang commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Types of changes

Documentation and example update.

Motivation and context / Related issue

Related to #890.

I extended the existing 2D partial Wasserstein example to make the meaning of m clearer. It explains absolute mass, point counts, and the fractions used when the input totals differ.

I shortened the added discussion in the user guide to one sentence linking to the example. I removed the in/out table and updated the source and target bar plots with full group names and a larger legend. The example now compares eight values of m on the same samples. The four transport-plan panels are still shown for m=0.25, 0.5, 0.75, and 1.

I kept the original sampling structure, Euclidean costs and existing solvers, and added a local fixed seed for reproducibility. The original entropic and Gromov-Wasserstein sections and attribution are still there. The example checks transported mass, marginal limits and the balanced endpoint when both totals are one. The bars show how much mass each group contributes, not whether individual points are correctly matched.

How has this been tested (if it applies)

Checked locally on Python 3.12 with the NumPy CPU backend after syncing the PR branch to dc79138:

  • Available upstream CPU tests and focused partial/LP doctests passed. The example checks transported mass, marginal capacities and the balanced endpoint during execution.
  • A focused Sphinx HTML gallery build completed; the selected example executed and both added figures were checked. Existing documentation diagnostics are unchanged from the preceding build.
  • Ruff and formatting checks passed.

PR checklist

@JaylenTang
JaylenTang marked this pull request as ready for review October 26, 2026 14:33
@JaylenTang

Copy link
Copy Markdown
Contributor Author

Hi @rflamary, I've added an initial implementation of the idea in #890 to this PR. When you have a chance, could you let me know whether this would be a useful addition to the documentation? I'm happy to adjust the scope. Thanks!

@codecov

codecov Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.09%. Comparing base (7d51e72) to head (60ed8ff).

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #902   +/-   ##
=======================================
  Coverage   97.09%   97.09%           
=======================================
  Files         130      130           
  Lines       27229    27229           
=======================================
  Hits        26437    26437           
  Misses        792      792           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@rflamary rflamary left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks for the PR @JaylenTang , I have some suggestions below about shortening the user guide and about the new info in the exmaple.

Comment thread docs/source/user_guide.rst Outdated
application, or validation suited to that application, can inform the choice.
Inspecting several feasible masses helps show the consequences of that choice.

The :ref:`2D partial Wasserstein example

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

this discussion is interesting but much too detailed for a user's guide. you can eitehr move it to the exmaple file where it makes more sens or remove it. only keep a sentence with areference to the example please.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Hi @rflamary, I’ll shorten the user guide and keep the detailed explanation in the example.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I shortened this to one sentence linking to the example and kept the explanation in the example.

)

print("\nExact partial Wasserstein mass study (raw transport costs):")
print(" m cost source in source out target in target out any out")

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

names are unclear please dont' use in and out that can mean source/target in OT but inlier outlier possibly . Actually it would porably be more clear with aplot (and maybe more valyues of m?) where you can have larger legends for the plots

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I’ll also use plots with clearer labels and larger legends, and include a few more values of m.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I removed the in/out table and updated the source and target bar plots with full group names and a larger legend. The example now compares eight values of m on the same samples.

@JaylenTang JaylenTang changed the title [WIP] Clarify transported mass in partial OT [MRG] Clarify transported mass in partial OT Nov 9, 2026
@JaylenTang

Copy link
Copy Markdown
Contributor Author

Hi @rflamary, just following up on the changes I pushed last week. I shortened the guide and updated the plots as you suggested. When you have a chance, could you take another look? Thanks!

@rflamary
rflamary merged commit 700fc19 into PythonOT:master Nov 17, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants