Ready for publication.

Author: kunaldahiya

README.md

@@ -2,16 +2,6 @@
 
 Code for _DeepXML: A Deep Extreme Multi-Label Learning Framework Applied to Short Text Documents_
 
-## Requirements
-
----
-
-* Pyxclib
-* NumPy
-* PyTorch
-* Numba
-* Scikit-learn
-
 ---
 
 ## Architectures and algorithms
@@ -32,54 +22,65 @@ DeepXML supports multiple feature architectures such as Bag-of-embedding/Astec,
 
 ---
 
-## Example use cases
+## Setting up
 
 ---
 
-### A single learner with DeepXML framework
+### Expected directory structure
 
-The DeepXML framework can be utilized as follows. A json file is used to specify architecture and other arguments.
+```txt
++-- <work_dir>
+|  +-- programs
+|  |  +-- deepxml
+|  |    +-- deepxml
+|  +-- data
+|    +-- <dataset>
+|  +-- models
+|  +-- results
 
-```bash
-./run_main.sh 0 DeepXML EURLex-4K 0 108
 ```
 
-### An ensemble of multiple learners with DeepXML framework
+### Download data for Astec
 
-An ensemble can be trained as follows. A json file is used to specify architecture and other arguments.
+```txt
+* Download the (zipped file) BoW features from XML repository.  
+* Extract the zipped file into data directory. 
+* The following files should be available in <work_dir>/data/<dataset>
+    - train.txt
+    - test.txt
+    - fasttextB_embeddings_300d.npy or fasttextB_embeddings_512d.npy 
+```
 
-```bash
-./run_main.sh 0 DeepXML EURLex-4K 0 108,666,786
+### Convert to new data format
+
+```perl
+# A perl script is provided (in deepxml/tools) to convert the data into new format as expected by Astec
+# Either set the $data_dir variable to the data directory of a particular dataset or replace it with the path
+perl convert_format.pl $data_dir/train.txt $data_dir/trn_X_Xf.txt $data_dir/trn_X_Y.txt
+perl convert_format.pl $data_dir/test.txt $data_dir/tst_X_Xf.txt $data_dir/tst_X_Y.txt
 ```
 
-## Full documentation
+## Example use cases
 
 ---
 
-### Expected directory structure
+### A single learner with DeepXML framework
 
-```txt
-+-- work_dir
-|  +-- programs
-|  |  +-- deepxml
-|  |    +-- deepxml
-|  +-- data_dir
-|    +-- dataset
-|  +-- model_dir
-|  +-- results_dir
+The DeepXML framework can be utilized as follows. A json file is used to specify architecture and other arguments. Please refer to the full documentation below for more details.
 
+```bash
+./run_main.sh 0 DeepXML EURLex-4K 0 108
 ```
 
-### Convert the data to new format
+### An ensemble of multiple learners with DeepXML framework
 
-```perl
-# A perl script is provided (deepxml/tools) to convert the data into new format as expected by DeepXML
-perl convert_format.pl <data_dir>/train.txt <data_dir>/trn_X_Xf.txt <data_dir>/trn_X_Y.txt
+An ensemble can be trained as follows. A json file is used to specify architecture and other arguments.
 
-perl convert_format.pl <data_dir>/test.txt <data_dir>/tst_X_Xf.txt <data_dir>/tst_X_Y.txt
+```bash
+./run_main.sh 0 DeepXML EURLex-4K 0 108,666,786
 ```
 
-### Run details
+## Full Documentation
 
 ```txt
 ./run_main.sh <gpu_id> <framework> <dataset> <version> <seed>
@@ -93,12 +94,13 @@ perl convert_format.pl <data_dir>/test.txt <data_dir>/tst_X_Xf.txt <data_dir>/ts
 
 * dataset
   - Name of the dataset.
-  - Expected files in work_dir/data/<dataset>
+  - Astec expects the following files in <work_dir>/data/<dataset>
     - trn_X_Xf.txt
     - trn_X_Y.txt
     - tst_X_Xf.txt
     - tst_X_Y.txt
-    - fasttextB_embeddings_300d.npy or fasttextB_embeddings_512d.npy 
+    - fasttextB_embeddings_300d.npy or fasttextB_embeddings_512d.npy
+  - You can set the 'embedding_dims' in config file to switch between 300d and 512d embeddings.
 
 * version
   - different runs could be managed by version and seed.

deepxml/configs/DeepXML/AmazonTitles-2.5M.json

@@ -12,6 +12,7 @@
         "embedding_dims": 300,
         "beta": 0.10,
         "top_k": 300,
+        "save_top_k": 100,
         "save_predictions": true, 
         "trn_label_fname": "trn_X_Y.txt",
         "val_label_fname": "tst_X_Y.txt",
@@ -36,7 +37,7 @@
     "extreme": {
         "num_epochs": 15,
         "dlr_factor": 0.5,
-        "learning_rate": 0.002,
+        "learning_rate": 0.0005,
         "batch_size": 255,
         "dlr_step": 14,
         "ns_method": "ensemble",

deepxml/configs/DeepXML/AmazonTitles-3M.json

@@ -25,7 +25,7 @@
         "dlr_factor": 0.5,
         "learning_rate": 0.02,
         "batch_size": 255,
-        "dlr_step": 14,
+        "dlr_step": 10,
         "normalize": true,
         "optim": "Adam",
         "init": "token_embeddings",

deepxml/configs/DeepXML/AmazonTitles-670K.json

@@ -1,4 +1,5 @@
 {
+    "representation_dims": "#ARGS.embedding_dims;",
     "transform_coarse": {
         "order": ["_identity"],
         "_identity": {}

deepxml/run_scripts/Identity.json

@@ -36,7 +36,7 @@ def create_surrogate_mapping(data_dir, g_config, seed):
     return data_stats, mapping
 
 
-def evaluate(g_config, data_dir, pred_fname, betas=-1, n_learners=1):
+def evaluate(g_config, data_dir, pred_fname, filter_fname=None, betas=-1, n_learners=1):
     if n_learners == 1:
         func = evalaute_one.main
     else:
@@ -46,14 +46,20 @@ def evaluate(g_config, data_dir, pred_fname, betas=-1, n_learners=1):
     data_dir = os.path.join(data_dir, dataset)
     A = g_config['A']
     B = g_config['B']
+    if 'save_top_k' in g_config:
+        top_k = g_config['save_top_k']
+    else:
+        top_k = g_config['top_k']
     ans = func(
         tst_label_fname=os.path.join(
             data_dir, g_config["tst_label_fname"]),
         trn_label_fname=os.path.join(
             data_dir, g_config["trn_label_fname"]),
         pred_fname=pred_fname,
         A=A, 
-        B=B, 
+        B=B,
+        top_k=top_k,
+        filter_fname=filter_fname, 
         betas=betas, 
         save=g_config["save_predictions"])
     return ans
@@ -86,6 +92,11 @@ def run_deepxml(work_dir, version, seed, config):
 
     # Directory and filenames
     data_dir = os.path.join(work_dir, 'data')
+
+    filter_fname = os.path.join(data_dir, dataset, 'filter_labels_test.txt')
+    if not os.path.isfile(filter_fname):
+        filter_fname = None
+    
     result_dir = os.path.join(
         work_dir, 'results', 'DeepXML', arch, dataset, f'v_{version}')
     model_dir = os.path.join(
@@ -158,6 +169,7 @@ def run_deepxml(work_dir, version, seed, config):
         g_config=g_config,
         data_dir=data_dir,
         pred_fname=pred_fname,
+        filter_fname=filter_fname,
         betas=[0.10, 0.20, 0.30, 0.40, 0.50, 0.60, 0.75, 0.90])
     f_rstats = os.path.join(result_dir, 'log_eval.txt')
     with open(f_rstats, "w") as fp:
@@ -220,6 +232,7 @@ def run_deepxml(work_dir, version, seed, config):
         ans = evaluate(
             g_config=g_config,
             data_dir=data_dir,
+            filter_fname=filter_fname,
             pred_fname=pred_fname,
             betas=[0.10, 0.20, 0.30, 0.40, 0.50, 0.60, 0.75, 0.90])
         with open(f_rstats, 'a') as fp:
@@ -241,6 +254,9 @@ def run_deepxml_ova(work_dir, version, seed, config):
         work_dir, 'results', 'DeepXML-OVA', arch, dataset, f'v_{version}')
     model_dir = os.path.join(
         work_dir, 'models', 'DeepXML-OVA', arch, dataset, f'v_{version}')
+    filter_fname = os.path.join(data_dir, dataset, 'filter_labels_test.txt')
+    if not os.path.isfile(filter_fname):
+        filter_fname = None
 
     _args = parameters.Parameters("Parameters")
     _args.parse_args()
@@ -279,6 +295,7 @@ def run_deepxml_ova(work_dir, version, seed, config):
     pred_fname = os.path.join(result_dir, 'tst_predictions')
     ans = evaluate(
         g_config=g_config,
+        filter_fname=filter_fname,
         data_dir=data_dir,
         pred_fname=pred_fname)
     f_rstats = os.path.join(result_dir, 'log_eval.txt')
@@ -300,6 +317,9 @@ def run_deepxml_ann(work_dir, version, seed, config):
         work_dir, 'results', 'DeepXML-ANNS', arch, dataset, f'v_{version}')
     model_dir = os.path.join(
         work_dir, 'models', 'DeepXML-ANNS', arch, dataset, f'v_{version}')
+    filter_fname = os.path.join(data_dir, dataset, 'filter_labels_test.txt')
+    if not os.path.isfile(filter_fname):
+        filter_fname = None
     _args = parameters.Parameters("Parameters")
     _args.parse_args()
     _args.update(config['global'])
@@ -339,6 +359,7 @@ def run_deepxml_ann(work_dir, version, seed, config):
     pred_fname = os.path.join(result_dir, 'tst_predictions')
     ans = evaluate(
         g_config=g_config,
+        filter_fname=filter_fname,
         data_dir=data_dir,
         pred_fname=pred_fname,
         betas=[0.10, 0.20, 0.30, 0.40, 0.50, 0.60, 0.75, 0.90])