update descriptions

doc/README.md

@@ -13,21 +13,12 @@ $ pip install -e ".[doc]"
 
 You can generate local HTML manually using sphinx Makefile
 
-```sh
-$ cd <espnet_root>/doc
-$ make html
-```
-
-`index.html` will be created at `doc/_build/html/index.html`
-
-or using travis-sphinx
-
 ```sh
 $ cd <espnet_root>
-$ travis-sphinx build --source=doc --nowarn
+$ ./ci/doc.sh
 ```
 
-`index.html` will be created at `doc/build/index.html`
+open `doc/build/html/index.html`
 
 ## Deploy
 

doc/gen_rst_py_tool.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 import importlib.machinery as imm
 import importlib.util as iu
+import logging
 import pathlib
 import re
 import os
@@ -32,18 +33,16 @@ def __init__(self, path):
 modinfo = []
 
 for p in args.src:
-    try:
-        modinfo.append(ModuleInfo(p))
-    except (ValueError, ModuleNotFoundError) as e:
-        import logging
-        logging.warning(f"ignore {p} ({e})")
+    if "__init__.py" in p:
+        continue
+    modinfo.append(ModuleInfo(p))
 
 
 # print refs
 for m in modinfo:
+    logging.info(f"processing: {m.path.name}")
     d = m.module.get_parser().description
-    if d is None:
-        d = "(no description provided)"
+    assert d is not None
     print(f"- :ref:`{m.path.name}`: {d}")
 
 print()

utils/compute-fbank-feats.py

@@ -15,8 +15,9 @@
 from espnet.utils.cli_utils import get_commandline_args
 
 
-def main():
+def get_parser():
     parser = argparse.ArgumentParser(
+        description='compute FBANK feature from WAV',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
     parser.add_argument('--fs', type=int,
                         help='Sampling frequency')
@@ -58,6 +59,11 @@ def main():
              '<segment-id> <recording-id> <start-time> <end-time>'
              'e.g. call-861225-A-0050-0065 call-861225-A 5.0 6.5')
     parser.add_argument('wspecifier', type=str, help='Write specifier')
+    return parser
+
+
+def main():
+    parser = get_parser()
     args = parser.parse_args()
 
     logfmt = "%(asctime)s (%(module)s:%(lineno)d) %(levelname)s: %(message)s"

utils/compute-stft-feats.py

@@ -15,8 +15,9 @@
 from espnet.utils.cli_utils import get_commandline_args
 
 
-def main():
+def get_parser():
     parser = argparse.ArgumentParser(
+        description='compute STFT feature from WAV',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
     parser.add_argument('--n_fft', type=int, default=1024,
                         help='FFT length in point')
@@ -50,6 +51,11 @@ def main():
              '<segment-id> <recording-id> <start-time> <end-time>'
              'e.g. call-861225-A-0050-0065 call-861225-A 5.0 6.5')
     parser.add_argument('wspecifier', type=str, help='Write specifier')
+    return parser
+
+
+def main():
+    parser = get_parser()
     args = parser.parse_args()
 
     logfmt = "%(asctime)s (%(module)s:%(lineno)d) %(levelname)s: %(message)s"

utils/convert_fbank_to_wav.py

@@ -42,8 +42,9 @@ def griffin_lim(spc, n_fft, n_shift, win_length, window='hann', iters=100):
     return y
 
 
-def main():
+def get_parser():
     parser = argparse.ArgumentParser(
+        description='convert FBANK to WAV using Griffin-Lim algorithm',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
     parser.add_argument('--fs', type=int, default=22050,
                         help='Sampling frequency')
@@ -71,6 +72,11 @@ def main():
     parser.add_argument('rspecifier', type=str, help='Input feature')
     parser.add_argument('outdir', type=str,
                         help='Output directory')
+    return parser
+
+
+def main():
+    parser = get_parser()
     args = parser.parse_args()
 
     # logging info

utils/copy-feats.py

@@ -10,8 +10,9 @@
 from espnet.utils.cli_utils import is_scipy_wav_style
 
 
-def main():
+def get_parser():
     parser = argparse.ArgumentParser(
+        description='copy feature with preprocessing',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
 
     parser.add_argument('--verbose', '-V', default=0, type=int,
@@ -36,6 +37,11 @@ def main():
                         help='Read specifier for feats. e.g. ark:some.ark')
     parser.add_argument('wspecifier', type=str,
                         help='Write specifier. e.g. ark:some.ark')
+    return parser
+
+
+def main():
+    parser = get_parser()
     args = parser.parse_args()
 
     # logging info

utils/eval-source-separation.py

@@ -197,7 +197,7 @@ def eval_PESQ(ref, enh, fs, compute_permutation=True):
     return tuple(value), tuple(perm)
 
 
-def main():
+def get_parser():
     parser = argparse.ArgumentParser(
         description='Evaluate enhanced speech. '
                     'e.g. {c} --ref ref.scp --enh enh.scp --outdir outputdir'
@@ -234,6 +234,11 @@ def main():
     parser.add_argument('--bss-eval-version', type=str,
                         default='v3', choices=['v3', 'v4'],
                         help='Specify bss-eval-version: v3 or v4')
+    return parser
+
+
+def main():
+    parser = get_parser()
     args = parser.parse_args()
 
     logfmt = "%(asctime)s (%(module)s:%(lineno)d) %(levelname)s: %(message)s"

utils/eval_perm_free_error.py

@@ -1,23 +1,88 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 # encoding: utf-8
 
 # Copyright 2019 Johns Hopkins University (Xuankai Chang)
 #  Apache 2.0  (http://www.apache.org/licenses/LICENSE-2.0)
-from __future__ import print_function
-from __future__ import unicode_literals
-
 import argparse
 import codecs
 import json
 import logging
-import numpy as np
 import re
 import six
 import sys
 
-from min_perm_wer import get_utt_permutation
+import numpy as np
+
+
+def permutationDFS(source, start, res):
+    # get permutations with DFS
+    # return order in [[1, 2], [2, 1]] or
+    # [[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 2, 1], [3, 1, 2]]
+    if start == len(source) - 1:  # reach final state
+        res.append(source.tolist())
+    for i in range(start, len(source)):
+        # swap values at position start and i
+        source[start], source[i] = source[i], source[start]
+        permutationDFS(source, start + 1, res)
+        # reverse the swap
+        source[start], source[i] = source[i], source[start]
+
+
+# pre-set the permutation scheme (ref_idx, hyp_idx)
+def permutation_schemes(num_spkrs):
+    src = [x for x in range(1, num_spkrs + 1)]
+    perms = []
+
+    # get all permutations of [1, ..., num_spkrs]
+    # [[r1h1, r2h2], [r1h2, r2h1]]
+    # [[r1h1, r2h2, r3h3], [r1h1, r2h3, r3h2], [r1h2, r2h1, r3h3],
+    #  [r1h2, r2h3, r3h2], [r1h3, r2h2, r3h1], [r1h3, r2h1, r3h2]]]
+    # ...
+    permutationDFS(np.array(src), 0, perms)
+
+    keys = []
+    for perm in perms:
+        keys.append(['r%dh%d' % (i, j) for i, j in enumerate(perm, 1)])
+
+    return sum(keys, []), keys
+
 
-is_python2 = sys.version_info[0] == 2
+def convert_score(keys, dic):
+    ret = {}
+    pat = re.compile(r'\d+')
+    for k in keys:
+        score = dic[k]['Scores']
+        score = list(map(int, pat.findall(score)))  # [c,s,d,i]
+        assert len(score) == 4
+        ret[k] = score
+    return ret
+
+
+def get_utt_permutation(old_dic, num_spkrs=2):
+    perm, keys = permutation_schemes(num_spkrs)
+    new_dic = {}
+
+    for id in old_dic.keys():
+        # compute error rate for each utt
+        in_dic = old_dic[id]
+        score = convert_score(perm, in_dic)
+        perm_score = []
+        for ks in keys:
+            tmp_score = [0, 0, 0, 0]
+            for k in ks:
+                tmp_score = [tmp_score[i] + score[k][i] for i in range(4)]
+            perm_score.append(tmp_score)
+
+        error_rate = [sum(s[1:4]) / float(sum(s[0:3])) for s in perm_score]  # (s+d+i) / (c+s+d)
+
+        min_idx, min_v = min(enumerate(error_rate), key=lambda x: x[1])
+        dic = {}
+        for k in keys[min_idx]:
+            dic[k] = in_dic[k]
+        dic['Scores'] = '(#C #S #D #I) ' + ' '.join(map(str, perm_score[min_idx]))
+        new_dic[id] = dic
+
+    return new_dic
 
 
 def get_results(result_file, result_key):
@@ -88,14 +153,19 @@ def merge_results(results):
     return dic
 
 
-def main():
-    parser = argparse.ArgumentParser()
+def get_parser():
+    parser = argparse.ArgumentParser(description='evaluate permutation-free error')
     parser.add_argument('--num-spkrs', type=int, default=2,
                         help='number of mixed speakers.')
     parser.add_argument('results', type=str, nargs='+',
                         help='the scores between references and hypotheses, '
                              'in ascending order of references (1st) and hypotheses (2nd), '
                              'e.g. [r1h1, r1h2, r2h1, r2h2] in 2-speaker-mix case.')
+    return parser
+
+
+def main():
+    parser = get_parser()
     args = parser.parse_args()
 
     if len(args.results) != args.num_spkrs ** 2:
@@ -129,7 +199,7 @@ def main():
 
 
 if __name__ == "__main__":
-    sys.stdout = codecs.getwriter('utf-8')(sys.stdout if is_python2 else sys.stdout.buffer)
+    sys.stdout = codecs.getwriter('utf-8')(sys.stdout.buffer)
 
     scores, new_results = main()
     score_sum = np.sum(scores, axis=0, dtype=int)

utils/feat-to-shape.py

@@ -11,8 +11,9 @@
 PY2 = sys.version_info[0] == 2
 
 
-def main():
+def get_parser():
     parser = argparse.ArgumentParser(
+        description='convert feature to its shape',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
     parser.add_argument('--verbose', '-V', default=0, type=int,
                         help='Verbose option')
@@ -28,7 +29,11 @@ def main():
                         default=sys.stdout,
                         help='The output filename. '
                              'If omitted, then output to sys.stdout')
+    return parser
+
 
+def main():
+    parser = get_parser()
     args = parser.parse_args()
 
     # logging info

utils/json2sctm.py

@@ -6,15 +6,12 @@
 import subprocess
 import sys
 
-from utils import json2trn
-from utils import trn2ctm
-from utils import trn2stm
 
 is_python2 = sys.version_info[0] == 2
 
 
-def main(args):
-    parser = argparse.ArgumentParser()
+def get_parser():
+    parser = argparse.ArgumentParser(description='convert json to sctm')
     parser.add_argument('json', type=str, default=None, nargs='?',
                         help='input trn')
     parser.add_argument('dict', type=str, help='dict')
@@ -25,6 +22,15 @@ def main(args):
     parser.add_argument('--stm', type=str, default=None, nargs='+', help='output stm')
     parser.add_argument('--ctm', type=str, default=None, nargs='+', help='output ctm')
     parser.add_argument('--bpe', type=str, default=None, nargs='?', help='BPE model if applicable')
+    return parser
+
+
+def main(args):
+    from utils import json2trn
+    from utils import trn2ctm
+    from utils import trn2stm
+
+    parser = get_parser()
     args = parser.parse_args(args)
     if args.refs is None:
         refs = ["ref_tmp.trn"]

utils/json2trn_mt.py

@@ -15,8 +15,9 @@
 from espnet.utils.cli_utils import get_commandline_args
 
 
-def main(args):
+def get_parser():
     parser = argparse.ArgumentParser(
+        description='convert json to machine translation transcription',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
     parser.add_argument('json', type=str, help='json files')
     parser.add_argument('dict', type=str, help='dict for target language')
@@ -25,6 +26,11 @@ def main(args):
     parser.add_argument('--srcs', type=str, nargs='+', help='src for all outputs')
     parser.add_argument('--dict-src', type=str, help='dict for source language',
                         default=False, nargs='?')
+    return parser
+
+
+def main(args):
+    parser = get_parser()
     args = parser.parse_args(args)
     convert(args.json, args.dict, args.refs, args.hyps, args.srcs, args.dict_src)
 

utils/merge_scp2json.py

@@ -41,7 +41,7 @@ def shape(x):
     return list(map(int, x.split(',')))
 
 
-if __name__ == '__main__':
+def get_parser():
     parser = argparse.ArgumentParser(
         description='Given each file paths with such format as '
                     '<key>:<file>:<type>. type> can be omitted and the default '
@@ -65,7 +65,11 @@ def shape(x):
     parser.add_argument('--out', '-O', type=str,
                         help='The output filename. '
                              'If omitted, then output to sys.stdout')
+    return parser
+
 
+if __name__ == '__main__':
+    parser = get_parser()
     args = parser.parse_args()
     args.scps = [args.scps]