Crosslingual Embeddings Refactored (#246)

* Refactored code

* Changed as requested in refactor

* Changed MD to RST, added function documentation, fixed paths

* Style fixes

* Added citations

* Corrected Citations

* Fixed citations again

* Style fix

* Refactored code

* Changed as requested in refactor

* Changed MD to RST, added function documentation, fixed paths

* Style fixes

* Added citations

* Corrected Citations

* Fixed citations again

* Style fix

* Updated crosslingual_emb.rst

Author: chinnikrishna2231

doc/source/assets/w2w.png

@@ -0,0 +1,66 @@
+Unsupervised Crosslingual Embeddings
+####################################
+
+Overview
+========
+This model uses a GAN to learn mapping between two language embeddings without supervision as demonstrated in Word Translation Without Parallel Data [1]_.
+
+.. image:: assets/w2w.png
+
+
+Files
+=====
+- **nlp_architect/data/fasttext_emb.py**: Defines fasttext object for loading fasttext embeddings
+- **nlp_architect/models/crossling_emb.py**: Defines GAN for learning crosslingual embeddings
+- **examples/crosslingembs/train.py**: Trains the model and writes final crosslingual embeddings to weight_dir directory.
+- **examples/crosslingembs/evaluate.py**: Defines graph for evaluating the quality of crosslingual embeddings
+
+Usage
+=====
+Main arguments which need to be passed to train.py are
+
+- **emb_dir**: Directory where fasttext embeddings are present or need to be downloaded
+- **eval_dir**: Directory where evaluation dictionary is downloaded
+- **weight_dir**: Directory where final crosslingual dictionaries are defined
+
+Use the following command to run training and generate crosslingual embeddings file:
+
+.. code:: python
+
+  python train.py --data_dir <embedding dir> --eval_dir <evaluation data> \
+    --weight_dir <save_data> --epochs 1
+
+Example Usage
+---------------
+
+Make directories for storing downloaded embeddings and multi language evaluation dictionaries
+
+.. code:: bash
+
+  mkdir data
+  mkdir ./data/crosslingual/dictionaries
+
+Run training sequence pointing to embedding directory and multi language evaluation dictionaries. After training it will store the mapping weight and new cross lingual embeddings in weight_dir
+
+.. code:: python
+
+  python train.py --data_dir ./data --eval_dir ./data/crosslingual/dictionaries --weight_dir ./
+
+Results
+=======
+
+When trained on English and French embeddings the results for word to word translation accuracy are as follows
+
+.. csv-table::
+  :header: "Eval Method ",K=1, K=10
+  :widths: 25, 20, 20
+  :escape: ~
+
+  NN,53.0,74.13
+  CSLS,81.0, "93.0 "
+
+
+References
+==========
+.. [1] Alexis Conneau, Guillaume Lample, Marc’Aurelio Ranzato, Ludovic Denoyer, Herve Jegou Word Translation Without Parallel Data https://arxiv.org/pdf/1710.04087.pdf
+.. [2] P.Bojanowski, E. Grave, A. Joulin, T. Mikolov, Enriching Word Vectors with Subword Information https://arxiv.org/abs/1607.04606

doc/source/crosslingual_emb.rst

@@ -57,6 +57,7 @@ The library contains state-of-art and novel NLP and NLU models in a varity of to
 - NER and NE expansion
 - Text chunking
 - Reading comprehension
+- Crosslingual Embeddings
 - Supervised sentiment analysis
 
 
@@ -118,6 +119,7 @@ on this project, please see the :doc:`developer guide <developer_guide>`.
    np2vec.rst
    supervised_sentiment.rst
    tcn.rst
+   Unsupervised Crosslingual Embeddings <crosslingual_emb.rst>
 
 .. toctree::
    :hidden:

doc/source/index.rst

@@ -0,0 +1,19 @@
+# UNSUPERVISED CROSSLINGUAL EMBEDDINGS
+This model learns crosslingual embedding in an unsupervised manner using GANs as demonstrated in
+Word Translation Without Parallel Data by Alexis Conneau et al.,
+
+
+Use the following command to run training and generate crosslingual embeddings file
+
+```python train.py --data_dir <embedding dir> --eval_dir <evaluation data> --weight_dir <save_data> --epochs 1```
+
+Example Usage
+```mkdir data```
+```mkdir ./data/crosslingual/dictionaries```
+```python train.py --data_dir ./data --eval_dir ./data/crosslingual/dictionaries --weight_dir ./ ```
+
+ Citations
+  ---------
+  1. Alexis Conneau, Guillaume Lample, Marc’Aurelio Ranzato, Ludovic Denoyer, Herve Jegou Word Translation Without Parallel Data https://arxiv.org/pdf/1710.04087.pdf
+  2. P. Bojanowski, E. Grave, A. Joulin, T. Mikolov, Enriching Word Vectors with Subword Information https://arxiv.org/abs/1607.04606
+