Example for 1D case of optimal transport

[davibarreira]

Recently in Julia's Slack, a person came asking about the 1D Wasserstein distance, and I realized that we don't have a clear example in the docs. So I wrote one. The example has both a continuous case and a discrete case.

[davibarreira]

I haven't written examples with Literate.jl before. I just created a new folder and followed a similar style to the other examples. Do I need to run a script to build the docs or does GitHub Actions takes care of it?

[codecov-commenter]

Codecov Report

Merging #147 (0bb1242) into master (59223df) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #147   +/-   ##
=======================================
  Coverage   95.31%   95.31%           
=======================================
  Files          14       14           
  Lines         619      619           
=======================================
  Hits          590      590           
  Misses         29       29           

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 59223df...0bb1242. Read the comment docs.

[coveralls]

Pull Request Test Coverage Report for Build 1365635412

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 95.315%

---

Totals
Change from base Build 1261409805:	0.0%
Covered Lines:	590
Relevant Lines:	619

---

💛 - Coveralls

[devmotion]

I haven't written examples with Literate.jl before. I just created a new folder and followed a similar style to the other examples. Do I need to run a script to build the docs or does GitHub Actions takes care of it?

Yes, this is correct, one just has to use the same structure as the existing examples. The script docs/make.jl (which is also executed by the Github action) runs all examples in these subfolders automatically.

Currently, the example fails since the Project.toml (and I assume Manifest.toml) do not include the Distributions dependency: https://github.com/JuliaOptimalTransport/OptimalTransport.jl/pull/147/checks?check_run_id=3957270384#step:8:22 The Project.toml should list all dependencies of the example (including Literate and OptimalTransport; the latter you should add with a relative path, e.g., with ] dev ../..: https://github.com/JuliaOptimalTransport/OptimalTransport.jl/blob/59223df8db5a6e776d87244b7e50eb57d60e89ae/examples/empirical_sinkhorn_div/Manifest.toml#L580). It seems you can simplify it a bit as well, e.g. you can remove PythonOT from the Project.toml here.

You can find some instructions regarding the examples here: https://github.com/JuliaGaussianProcesses/KernelFunctions.jl/tree/master/examples#add-a-new-example (we use the same setup)

[davibarreira]

I can't figure out why it's failing for windows. It looks like it's actually related to POT.

[devmotion]

Yeah, the installation of POT (the Python library, not the Julia package itself) is really unstable. There are quite many issues about it in their repo and it seems they plan to improve it in an upcoming release. I'll have a look within the next days if we can work around it somehow. In the worst case we could disable tests with Windows until it is fixed upstream.

Could you also build the docs locally and check it looks correct (maybe also post a screenshot)? The online preview does not work for PRs from forks (not our fault, it's a security feature from Github and checked in Documenter).

[davibarreira]

I'm getting erros when trying to build the docs. Right when I run make.jl I get:

ERROR: LoadError: ArgumentError: cannot find inputfile `/home/davibarreira/MEGA/EMAp/OptimalTransport.jl/examples/.ipynb_checkpoints/script.jl`
Stacktrace:
 [1] preprocessor(inputfile::String, outputdir::String; user_config::Dict{Any, Any}, user_kwargs::Base.Iterators.Pairs{Symbol, Any, NTuple{4, Symbol}, NamedTuple{(:name, :documenter, :execute, :preprocess), Tuple{String, Bool, Bool, typeof(preprocess)}}}, type::Symbol)
   @ Literate ~/.julia/packages/Literate/GWYEt/src/Literate.jl:383
 [2] markdown(inputfile::String, outputdir::String; config::Dict{Any, Any}, kwargs::Base.Iterators.Pairs{Symbol, Any, NTuple{4, Symbol}, NamedTuple{(:name, :documenter, :execute, :preprocess), Tuple{String, Bool, Bool, typeof(preprocess)}}})
   @ Literate ~/.julia/packages/Literate/GWYEt/src/Literate.jl:490
 [3] top-level scope
   @ ~/MEGA/EMAp/OptimalTransport.jl/docs/literate.jl:48

But the script keeps going, and it generates the markdown for the examples, but then I get another error saying:

ERROR: LoadError: some examples were not run successfully
Stacktrace:
 [1] error(s::String)
   @ Base ./error.jl:33
 [2] top-level scope
   @ ~/MEGA/EMAp/OptimalTransport.jl/docs/make.jl:37
 [3] include(fname::String)
   @ Base.MainInclude ./client.jl:444
 [4] top-level scope
   @ REPL[4]:1
in expression starting at /home/davibarreira/MEGA/EMAp/OptimalTransport.jl/docs/make.jl:37

And the build/ folder is not created. Any idea on what might be going on? It's strange that in the CI the docs are successfully built.

[devmotion]

You have to delete the hidden folder "example/.ipynb_checkpoints/". The script "docs/make.jl" tries to run a script.jl file in each of these folders and it can't be found in this subfolder. I guess we could change the script such that it only tries to run examples if the script.jl file actually exists but for now you can just delete this folder.

[davibarreira]

You have to delete the hidden folder "example/.ipynb_checkpoints/". The script "docs/make.jl" tries to run a script.jl file in each of these folders and it can't be found in this subfolder. I guess we could change the script such that it only tries to run examples if the script.jl file actually exists but for now you can just delete this folder.

Thanks, now it worked. There are some small adjustments in some of the math, cause I was using the double \\mu which looks like it's not the correct way with Literate. Also, the 1D page is coming before the Basics. Would you know how to fix this? I'm guessing that it's just doing the alphabetical order.

[davibarreira]

[davibarreira]

Are you guys good with this example?

[zsteve]

Yes, the example looks fine. Thanks for adding this!

[devmotion]

Seems POT 0.7.0 has some issues with Python 3.10 on Windows. I reverted to Python 3.9 for now. Just today a PR was merged in POT that will simplify the installation procedure significantly (no manual python -m pip install cython needed anymore), so we should clean our setup once POT 0.8 is released.

[davibarreira]

Good to go?

[devmotion]

Yep, thanks! I didn't want to wait until tests passed and then forgot about it :slightly_smiling_face: