[doc] add tutorial for kaldi pybind IO. (#3986)

Author: csukuangfj

src/pybind/.clang-format

@@ -0,0 +1,4 @@
+# Run manually to reformat a file:
+# clang-format -i --style=file <file>
+BasedOnStyle: Google
+DerivePointerAlignment: false

src/pybind/doc/conf.py

@@ -18,27 +18,25 @@
 # otherwise `import` will throw.
 import sphinx_rtd_theme
 
-
-
 # -- Project information -----------------------------------------------------
 
 project = 'Kaldi Pybind'
-copyright = '2020, Kaldi Pybind Authors'
+copyright = '2019-2020, Kaldi Pybind Authors'
 author = 'Kaldi Pybind Authors'
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-'sphinx.ext.autodoc',
-'sphinx.ext.autosummary',
-'sphinx.ext.mathjax',
-'sphinx.ext.napoleon',
-'sphinx.ext.todo',
-'sphinx.ext.viewcode',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -60,7 +58,6 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

src/pybind/doc/getting_started.rst

@@ -15,7 +15,7 @@ from
 
     Kaldi Pybind is still under active development and has not
     yet been merged into the master branch. You should checkout
-    the `pybind11` branch before compilation.
+    the ``pybind11`` branch before compilation.
 
 .. Note::
 
@@ -40,3 +40,15 @@ The following is a quick start:
     make
     make test
 
+After a successful compilation, you have to modify the environment
+variable ``PYTHONPATH``:
+
+.. code-block:: bash
+
+  export KALDI_ROOT=/path/to/your/kaldi
+  export PYTHONPATH=$KALDI_ROOT/src/pybind:$PYTHONPATH
+
+.. HINT::
+
+  There is no ``make install``. Once compiled, you are ready to
+  use Kaldi Pybind.

src/pybind/doc/index.rst

@@ -18,3 +18,10 @@ Welcome to Kaldi Pybind's documentation!
 
    introduction
    getting_started
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Tutorial
+
+    tutorial/working_with_kaldi_matrices
+    tutorial/working_with_kaldi_io

src/pybind/doc/introduction.rst

@@ -10,7 +10,7 @@ About Kaldi Pybind
 
 Kaldi Pybind is a Python wrapper for Kaldi
 using `Pybind11 <https://github.com/pybind/pybind11>`_.
+It is still under active development.
 
-Kaldi Pybind is still under active development.
 Everything related to Kaldi Pybind is put in the
 `pybind11 branch <https://github.com/kaldi-asr/kaldi/tree/pybind11>`_.

src/pybind/doc/tutorial/code/test_float_matrix.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+import kaldi
+
+f = kaldi.FloatMatrix(2, 3)
+f[1, 2] = 100
+print(f)
+
+g = f.numpy()
+g[0, 0] = 200
+print(f)

src/pybind/doc/tutorial/code/test_float_submatrix.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+
+import kaldi
+import numpy as np
+
+m = np.array([[1, 2, 3], [10, 20, 30]], dtype=np.float32)
+f = kaldi.FloatSubMatrix(m)
+
+f[1, 2] = 100
+print(m)
+print()
+
+g = f.numpy()
+g[0, 0] = 200
+print(m)

src/pybind/doc/tutorial/code/test_float_subvector.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+
+import kaldi
+import numpy as np
+
+v = np.array([10, 20, 30], dtype=np.float32)
+f = kaldi.FloatSubVector(v)
+
+f[0] = 0
+print(v)
+
+g = f.numpy()
+g[1] = 100
+print(v)

src/pybind/doc/tutorial/code/test_float_vector.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+import kaldi
+
+f = kaldi.FloatVector(3)
+f[0] = 10
+print(f)
+
+g = f.numpy()
+g[1] = 20
+print(f)

src/pybind/doc/tutorial/code/test_io_ali.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+
+import kaldi
+
+wspecifier = 'ark,scp:/tmp/ali.ark,/tmp/ali.scp'
+
+writer = kaldi.IntVectorWriter(wspecifier)
+writer.Write(key='foo', value=[1, 2, 3])
+writer.Write('bar', [10, 20])
+writer.Close()
+
+rspecifier = 'scp:/tmp/ali.scp'
+reader = kaldi.SequentialIntVectorReader(rspecifier)
+
+for key, value in reader:
+    print(key, value)
+
+reader.Close()
+
+reader = kaldi.RandomAccessIntVectorReader(rspecifier)
+value1 = reader['foo']
+print(value1)
+
+value2 = reader['bar']
+print(value2)
+reader.Close()

src/pybind/doc/tutorial/code/test_io_ali_2.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+
+import kaldi
+
+wspecifier = 'ark,scp:/tmp/ali.ark,/tmp/ali.scp'
+
+with kaldi.IntVectorWriter(wspecifier) as writer:
+    writer.Write(key='foo', value=[1, 2, 3])
+    writer.Write('bar', [10, 20])
+
+# Note that you do NOT need to close the file.
+
+rspecifier = 'scp:/tmp/ali.scp'
+with kaldi.SequentialIntVectorReader(rspecifier) as reader:
+    for key, value in reader:
+        print(key, value)
+
+rspecifier = 'scp:/tmp/ali.scp'
+with kaldi.RandomAccessIntVectorReader(rspecifier) as reader:
+    value1 = reader['foo']
+    print(value1)
+
+    value2 = reader['bar']
+    print(value2)

src/pybind/doc/tutorial/code/test_io_mat_specifier.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+
+import numpy as np
+import kaldi
+
+wspecifier = 'ark,scp:/tmp/feats.ark,/tmp/feats.scp'
+
+writer = kaldi.MatrixWriter(wspecifier)
+
+m = np.arange(6).reshape(2, 3).astype(np.float32)
+writer.Write(key='foo', value=m)
+
+g = kaldi.FloatMatrix(2, 2)
+g[0, 0] = 10
+g[1, 1] = 20
+writer.Write('bar', g)
+
+writer.Close()
+
+rspecifier = 'scp:/tmp/feats.scp'
+reader = kaldi.SequentialMatrixReader(rspecifier)
+for key, value in reader:
+    assert key in ['foo', 'bar']
+    if key == 'foo':
+        np.testing.assert_array_equal(value.numpy(), m)
+    else:
+        np.testing.assert_array_equal(value.numpy(), g.numpy())
+
+reader.Close()
+
+reader = kaldi.RandomAccessMatrixReader(rspecifier)
+assert 'foo' in reader
+assert 'bar' in reader
+np.testing.assert_array_equal(reader['foo'].numpy(), m)
+np.testing.assert_array_equal(reader['bar'].numpy(), g.numpy())
+reader.Close()

src/pybind/doc/tutorial/code/test_io_mat_specifier_2.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+
+import numpy as np
+import kaldi
+
+wspecifier = 'ark,scp:/tmp/feats.ark,/tmp/feats.scp'
+
+with kaldi.MatrixWriter(wspecifier) as writer:
+    m = np.arange(6).reshape(2, 3).astype(np.float32)
+    writer.Write(key='foo', value=m)
+
+    g = kaldi.FloatMatrix(2, 2)
+    g[0, 0] = 10
+    g[1, 1] = 20
+    writer.Write('bar', g)
+
+rspecifier = 'scp:/tmp/feats.scp'
+with kaldi.SequentialMatrixReader(rspecifier) as reader:
+    for key, value in reader:
+        assert key in ['foo', 'bar']
+        if key == 'foo':
+            np.testing.assert_array_equal(value.numpy(), m)
+        else:
+            np.testing.assert_array_equal(value.numpy(), g.numpy())
+
+with kaldi.RandomAccessMatrixReader(rspecifier) as reader:
+    assert 'foo' in reader
+    assert 'bar' in reader
+    np.testing.assert_array_equal(reader['foo'].numpy(), m)
+    np.testing.assert_array_equal(reader['bar'].numpy(), g.numpy())

src/pybind/doc/tutorial/code/test_io_mat_xfilename.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+
+import kaldi
+
+m = kaldi.FloatMatrix(2, 2)
+m[0, 0] = 10
+m[1, 1] = 20
+
+xfilename = '/tmp/lda.mat'
+kaldi.write_mat(m, xfilename, binary=True)
+
+g = kaldi.read_mat(xfilename)
+print(g)