Add Matching Explainer Algorithm

[fabianlim]

Summary

Adding a White Box Explainer for Matchings, as described in the upcoming ICML 2022 publication.

• the below algorithm is implemented in a python package, which is imported into AIX360

Fabian Lim, Laura Wynter, Shiau Hong Lim. 2022. "Order Constraints in Optimal Transport". https://arxiv.org/abs/2110.07275.

Algorithm

Given a matching, provide an explaination in terms of returning alternate matchings that each focus on a sparse set of salient matches.

• inherit from the LocalWBExplainer since it requires access to the internal coefficients of a matching (white box) and does not require retraining over a dataset (locality)

Package Dependencies

In setup.py we have the following dependency that is installed as an egg

• 'otoc @ git+https://github.com/IBM/otoc@main#egg=otoc'

In examples/matching/matching-pairs-of-sentences.ipynb we ask the user to install the below packages in order to execute the demo

• POT==0.7.0

Example

An NLP-based example inspired from one of the figures in the paper is provided

TODO

• [x] algorithm has been added in here.
• [x] semantic dataset used in examples has been included in here.
• [x] examples has been included in here. With the following 2 subdirectories
  • data: storing NLP embeddings that will be downloaded for the demo
  • models: contains code for an NLP embedding model used in demo
  • utils: utility functions for the demo
• [x] docs have been updated. Sphinx has been run locally and tested.
• [x] Update READMEs in examples, top-level directory, examples, etc
• [x] tests has been included in here.
  • data: each test case is specified in a .json file and stored here.
• [x] Update setup.py. The python package is hosted publically at https://github.com/IBM/otoc.
  • [x] This repo is placed in install_requires as an egg link
  • [x] Update the GitHub link in the top-level README
  • [ ] Discuss with @vijay-arya on where to move the below items
  • examples/matching/data
  • examples/matching/models
  • tests/matching/data

[lgtm-com[bot]]

This pull request introduces 4 alerts and fixes 2 when merging 83ee5e7937f5b727e242f2c57faffc5ccd206579 into e06d186eaa67a9f42b183372933e9bbad64d8fd5 - view on LGTM.com

new alerts:

• 4 for Module is imported with 'import' and 'import from'

fixed alerts:

• 2 for Module is imported with 'import' and 'import from'

[vijay-arya]

@fabianlim thanks! for integrating the optimal transport algorithm to aix360. The PR is merged.