Documentation/tutorial

[zoepiran]

Hi @Marius1311,
added the tutorials - hope it follows your line of thought.

• 'FGW-regimes'; wasn't sure how much more to get into it.
• simulated trajectory;
  (a) showing only the 'true tree' setting - I think it passes the point and this way we can refrain from forcing users only going through tutorial to install Cassipeia (and Gurobi etc.).
  (b) thought it is useful and understandable to use the benchmarking functions (rather than breaking them line by line) hence some of the explanations are maybe not as detailed.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[michalk8]

Would also enable 64-bit and add a sentence below why we do it (with 32-bit, sometimes the precision wasn't enough).

Reply via ReviewNB

[michalk8]

Line #4.    module_path = os.path.abspath(os.path.join('..'))

The local import seems unnecessary in this notebook, would remove it if that's the case.

Reply via ReviewNB

[michalk8]

Fix typos + maintain consistency (would start sentences capitalized + end with .)

Reply via ReviewNB

[michalk8]

Add some closing remarks.

Reply via ReviewNB

[michalk8]

Add link to the paper.

Furthermore, I'd format both notebooks using black (there should be some extension, can't remember its name).

Reply via ReviewNB

[michalk8]

Would use flow_types instead of integer indices (just like in Aden's notebook)

Reply via ReviewNB

[michalk8]

Would remove this cell and run below benchmark_moscot(sim, alpha=0, epsilon=epsilon) - just adds extra cell with little info.

Also applied for the other alphas (1, and 0.9).

Reply via ReviewNB

[michalk8]

Would all params (in this case scale) to one place (e.g. where you define epsilon

Reply via ReviewNB

[michalk8]

Tbh, not sure how informative this is, because of overplotting/the data.

To my eyes, OT, LOT and us look the same.

Reply via ReviewNB

[zoepiran]

I agree in terms of comparison; hence added the cost but thought it was beneficial to show how one can visualize easily the obtained mappings/. Am open for suggestions for better visuals here.

[michalk8]

I'd add some closing remark, summarizing what we've done/learned/...

Reply via ReviewNB

[Marius1311]

Thanks for the work on this @michalk8 and @zoepiran, and let me know once I should take a look

[zoepiran]

The current version has a after incorporation of @michalk8 comments

[Marius1311]

Are our results in the simple 1D example correct? In the original POT example, the selling point was that FGW is a best-of-both-worlds scenario: it preserves feature relations while also enforcing structural correspondence (Fig. 2). But that's not what we are showing (Fig. 1 below) - in our results, FGW looks just super similar to GW and the user if left wondering what the added benefit really is. We need to make this example more convincing. Also, at the moment, it's a bit confusing because x and y have different meanings throughout the notebook - they're at the same time the corresponding feature spaces for source and target, while also the x and y axis in the plots we show. I know this is also the case in the original POT tutorial, but I also find this confusing there. We should just improve the naming a bit. Also, I don't get why the features have two different names (a and b) - isn't the whole story here that features can be compared across spaces? So it should be the same feature we're looking at, no? On the other hand, the structural coordinates should have different names, maybe just not x and y, because that get's confusing. Also, when we shot the final couplings, it's a bit hard to relate this to what we had earlier because suddenly, there are i and j, which haven't been introduced before.

Fig. 1 (ours)

Fig. 2 (POT)

[Marius1311]

For a tutorial to be convincing, it just has to be super obvious - at the moment, we leave a lot of work on the users side to try and figure out what we're trying to sell here. We need to make this much clearer by improving nomenclature, descriptions and basically making sure our results also show a best-of-both-worlds scenario. Also, most users that come won't really understand what these two "extremal regimes" are, we need to add some explanations.

[Marius1311]

Also we need to give credit to the original POT example, not just to Vayer.

[Marius1311]

I did some minor edits on the text, but this needs some more work.

[zoepiran]

Are our results in the simple 1D example correct? In the original POT example, the selling point was that FGW is a best-of-both-worlds scenario: it preserves feature relations while also enforcing structural correspondence (Fig. 2). But that's not what we are showing (Fig. 1 below) - in our results, FGW looks just super similar to GW and the user if left wondering what the added benefit really is. We need to make this example more convincing. Also, at the moment, it's a bit confusing because x and y have different meanings throughout the notebook - they're at the same time the corresponding feature spaces for source and target, while also the x and y axis in the plots we show. I know this is also the case in the original POT tutorial, but I also find this confusing there. We should just improve the naming a bit. Also, I don't get why the features have two different names (a and b) - isn't the whole story here that features can be compared across spaces? So it should be the same feature we're looking at, no? On the other hand, the structural coordinates should have different names, maybe just not x and y, because that get's confusing. Also, when we shot the final couplings, it's a bit hard to relate this to what we had earlier because suddenly, there are i and j, which haven't been introduced before.

Fig. 1 (ours)

Fig. 2 (POT)

I briefly mentioned this in our previous meeting - I was also concerned with this and it got me to think again about the scaling again ... however in the POT example \alpha = 1e-3. Its my mistake i didn;t add this option here as well.
This is actually an interesting point to discuss with Cuturi - I would love to hear his take on scaling the costs and having \alpha as an actual accountable weight.

Digging more into it there are two ways to go:
[1] showing the results w/ \alpha = 1e-3 (reproducing POT)

[2] using our scale_fn leading to:

[Marius1311]

Thanks Zoe! Using our scale_fn, can we also recover a coupling similar to what we get with GW? i.e., is there a value of \alpha where FGW "flips"?

[Marius1311]

Other than that, did you have a chance to incorporate my suggestions yet? Let me know once you do, happy to go over this again.

[zoepiran]

For a tutorial to be convincing, it just has to be super obvious - at the moment, we leave a lot of work on the users side to try and figure out what we're trying to sell here. We need to make this much clearer by improving nomenclature, descriptions and basically making sure our results also show a best-of-both-worlds scenario. Also, most users that come won't really understand what these two "extremal regimes" are, we need to add some explanations.

I am afraid my main problem is that its not super clear to me what do we add on POT's tutorial here ..

[zoepiran]

I am sure there is; will manually look for it

[michalk8]

@zoepiran I had to close this PR to delete an old branch (old_dev).