add zh doc vis

yifanfeng97 · yifanfeng97 · commit 8e698b228d05 · 2022-09-27T10:49:14.000+08:00
diff --git a/docs/source/zh/tutorial/vis_feature.rst b/docs/source/zh/tutorial/vis_feature.rst
@@ -1,18 +1,198 @@
 特征可视化
 =========================
 
-即将上线！
+.. hint:: 
 
-.. Basic Usages
-.. ---------------
+    - 作者: 唐青梅
+    - 翻译：颜杰龙
+    - 校对: `丰一帆 <https://fengyifan.site/>`_
 
-.. draw feature in Euclidean space, draw feature in manifold space
+Basic Usages
+---------------
+DHG provides an interface to visualize the distribution of feaures:
 
-.. Make Animation
-.. -------------------------
+1. Input the features and lable (optional);
+2. Specify parameters (*i.e.*, `the dimensionality of the visualisation`, `point size`, `color` and `the method of dimensionality reduction`);
+3. Call ``plt.show()`` funtion to show the figure/animation. 
 
+   
+.. note:: The ``plt`` is short for ``matplotlib.pyplot`` module.
+
+
+Visualization of Features in Euclidean Space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../_static/img/vis_ft_euclidean.png
+    :align: center
+    :alt: Visualization of Features in Euclidean Space
+    :height: 400px
+
+
+.. code-block:: python
+
+    >>> import dhg
+    >>> import numpy as np
+    >>> import matplotlib.pyplot as plt
+    >>> import dhg.visualization as vis
+    >>> lbl = (np.random.rand(200)*10).astype(int)
+    >>> ft = dhg.random.normal_features(lbl)
+    >>> vis.draw_in_euclidean_space(ft, lbl)
+    >>> plt.show()
+
+
+Visualization of Features in Poincare Space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../_static/img/vis_ft_poincare.png
+    :align: center
+    :alt: Visualization of Features in Poincare Space
+    :height: 400px
+
+
+.. code-block:: python
+
+    >>> import dhg
+    >>> import numpy as np
+    >>> import matplotlib.pyplot as plt
+    >>> import dhg.visualization as vis
+    >>> lbl = (np.random.rand(200)*10).astype(int)
+    >>> ft = dhg.random.normal_features(lbl)
+    >>> vis.draw_in_poincare_space(ft, lbl)
+    >>> plt.show()
+
+
+Make Animation
+-------------------------
+
+We provide functions to make 3D rotation animation for feature visualization.
+
+Rotating Visualization of Features in Euclidean Space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../_static/img/vis_ft_euclidean_ani.png
+    :align: center
+    :alt: Rotating Visualization of Features in Euclidean Space
+    :height: 400px
+
+
+.. code-block:: python
+
+    >>> import dhg
+    >>> import numpy as np
+    >>> import matplotlib.pyplot as plt
+    >>> import dhg.visualization as vis
+    >>> lbl = (np.random.rand(200)*10).astype(int)
+    >>> ft = dhg.random.normal_features(lbl)
+    >>> vis.animation_of_3d_euclidean_space(ft, lbl)
+    >>> plt.show()
+
+.. 
+    >>> import numpy as np
+    >>> from dhg.visualization.feature import animation_of_3d_euclidean_ball
+    >>> ile_dir = "data/modelnet40/test_img_feat_4.npy"
+    >>> save_dir = None  # None for show now or file name to save
+    >>> label = np.load("data/modelnet40/test_label.npy")
+    >>> ft = np.load(file_dir)
+    >>> d = 3
+    >>> low_demen_method = "tsne"  # vis for poincare_ball: pca or tsne
+    >>> show_method = "Rotation"  # None for 2d or Rotation and Drag for 3d
+    >>> animation_of_3d_euclidean_ball(
+            ft, save_dir, d, label, reduce_method=low_demen_method, auto_play=show_method
+        )
+
+Rotating Visualization of Features in Poincare Space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../_static/img/vis_ft_poincare_ani.png
+    :align: center
+    :alt: Rotating Visualization of Features in Poincare Space
+    :height: 400px
+
+
+.. code-block:: python
+
+    >>> import dhg
+    >>> import numpy as np
+    >>> import matplotlib.pyplot as plt
+    >>> import dhg.visualization as vis
+    >>> lbl = (np.random.rand(200)*10).astype(int)
+    >>> ft = dhg.random.normal_features(lbl)
+    >>> vis.animation_of_3d_poincare_ball(ft, lbl)
+    >>> plt.show()
+
+..
+    >>> import numpy as np
+    >>> from dhg.visualization.feature import animation_of_3d_poincare_ball
+    >>> file_dir = "data/modelnet40/test_img_feat_4.npy" #This varies depending on the situation
+    >>> save_dir = None  # None for show now or file name to save
+    >>> label = np.load("data/modelnet40/test_label.npy")
+    >>> ft = np.load(file_dir)
+    >>> d = 3
+    >>> low_demen_method = "tsne"  # vis for poincare_ball, pca or tsne
+    >>> show_method = "Rotation"  # None for 2d or Rotation and Drag for 3d
+    >>> animation_of_3d_poincare_ball(
+            ft, save_dir, d, label, reduce_method=low_demen_method, auto_play=show_method
+        )
+
+
+
+Mathamatical Principles of Hyperbolic Space
+--------------------------------------------------
+
+The hyperbolic space is a manifold with constant Gaussian constant negative curvature everywhere, 
+which has several models. We base our work on the Poincaré ball model for its well-suited for gradient-based optimization. 
+
+The Poincaré ball model with constant negative curvature :math:`-1 / k(k>0)` corresponds to the 
+Riemannian manifold 
+:math:`\left(\mathbb{P}^{n,k},  g_{\mathbf{x}}^{\mathbb{P}}\right)`. 
+:math:`\mathbb{P}^{n,k} = \left\{\mathbf{x} \in \mathbb{R}^{n}: \| \mathbf{x}\|<1 \right\}` is an open :math:`n`-demensionsional unit ball, 
+where :math:`\|. \|` denotes the Euclidean norm. Its metric tensor is :math:`g_{\mathbf{x}}^{\mathbb{P}} = \lambda_{\mathbf{x}}^{2} g^{E}`, 
+where :math:`\lambda_{\mathbf{x}} = \frac{2} {1- k\|\mathbf{x}\|^{2} }` is the conformal factor and :math:`g^{E}=\mathbf{I}_{n}` is the Euclidean metric tensor. 
+For two points :math:`\mathbf{x}, \mathbf{y} \in \mathbb{P}^{n,k}`, we ues the Möbius addition :math:`\oplus` operate adding 
+by connecting the gyrospace framework with Riemannian geometry:
+
+.. math::
+
+    \mathbf{x} \oplus_{k} \mathbf{y} =\frac{\left(1+2k\langle\mathbf{x}, \mathbf{y}\rangle+k\|\mathbf{y}\|^{2}\right) \mathbf{x}+\left(1-k\|\mathbf{x}\|^{2}\right) \mathbf{y}}{1+2k\langle\mathbf{x}, \mathbf{y}\rangle+k^{2}\|\mathbf{x}\|^{2}\|\mathbf{y}\|^{2}} .
+
+The distance between two points :math:`\mathbf{x}, \mathbf{y} \in \mathbb{P}^{n,k}` is calculated by integration of the metric tensor, which is given as:
+
+.. math::
+
+    d_{\mathbb{P}}^{k} (\mathbf{x}, \mathbf{y}) = (2 / \sqrt{K}) \tanh ^{-1}\left(\sqrt{k}\left\|-x \oplus_{k} y\right\|\right) .
+
+
+Denote point :math:`\mathbf{z} \in \mathcal{T}_{\mathrm{x}} \mathbb{P}^{n,k}` the tangent (Euclidean) space centered at any point :math:`\mathbf{x}` in the hyperbolic space. 
+For the tangent vector :math:`\mathbf{z} \neq \mathbf{0}` and the point :math:`\mathbf{y} \neq \mathbf{0}`, 
+the exponential map :math:`\exp _{\mathbf{x}}: \mathcal{T}_{\mathbf{x}} \mathbb{P}^{n,k} \rightarrow \mathbb{P}^{n,k}` and 
+the logarithmic map :math:`\log_{\mathbf{x}}: \mathbb{P}^{n,k} \rightarrow \mathcal{T}_{\mathbf{x}} \mathbb{P}^{n,k}` are given for 
+:math:`\mathbf{y} \neq \mathbf{x}` by:
+
+.. math::
+
+    \exp _{\mathbf{x}}^{k}(\mathbf{z})=\mathbf{x} \oplus_{k}\left(\tanh \left(\sqrt{k} \frac{\lambda_{\mathbf{x}}^{k}\|\mathbf{z}\|}{2}\right) \frac{\mathbf{z}}{\sqrt{k}\|\mathbf{z}\|}\right), 
+
+and
+
+.. math::
+
+    \log _{\mathbf{x}}^{k}(\mathbf{y})=\frac{2}{\sqrt{k} \lambda_{\mathbf{x}}^{k}} \tanh ^{-1}\left(\sqrt{k}\left\|-\mathbf{x} \oplus_{k} \mathbf{y}\right\|\right) \frac{-\mathbf{x} \oplus_{k} \mathbf{y}}{\left\|-\mathbf{x} \oplus_{k} \mathbf{y}\right\|} .
+
+It is noted that our initial data are on Euclidean space and need to be converted to embeddings on hyperbolic space, so first project the data on the previously obtained Euclidean space onto the hyperbolic manifold space 
+in order to use the Spectral-based hypergraph hyperbolic convolutional network to learn the information to update the node embeddings. 
+Set :math:`t:=\{\sqrt{K}, 0, 0, \dots, 0\}\in\mathbb{P}^{d, K}` as a reference point to perform tangent space operations, 
+where :math:`-1/K` is the negative curvature of hyperbolic model. 
+The above premise makes :math:`\langle(0, \mathbf{x}^{0, E}), t\rangle=0` hold, 
+so :math:`(0, \mathbf{x}^{0, E})` can be regarded as the initial embedding representation of the hypergraph structure on the tangent plane 
+of the hyperbolic manifold space :math:`\mathcal{T}_t\mathbb{P}^{d, K}`. The initial hypergraph structure embedding is 
+then mapped onto the hyperbolic manifold space :math:`\mathbb{P}` using the following equation:
+
+.. math::
+
+    \mathbf{x}^{0, \mathbb{P}} &=\exp _{t}^{K}\left(\left(0, \mathbf{x}^{0, \mathrm{E}}\right)\right) \\
+    &=\left(\sqrt{K} \cosh \left(\frac{\left\|\mathbf{x}^{0, \mathbb{E}}\right\|_{2}}{\sqrt{K}}\right), 
+    \sqrt{K} \sinh \left(\frac{\left\|\mathbf{x}^{0, \mathbb{E}}\right\|_{2}}{\sqrt{K}}\right) \frac{\mathbf{x}^{0, \mathbb{E}}}{\left\|\mathbf{x}^{0, \mathbb{E}}\right\|_{2}}\right).
+
+The hyperbolic operation is accomplished by means of a feature mapping between Euclidean space and Hyperbolic space.
 
-.. Mathamatical Principles
-.. ---------------------------
 
-.. hyperbolic space
diff --git a/docs/source/zh/tutorial/vis_structure.rst b/docs/source/zh/tutorial/vis_structure.rst
@@ -1,15 +1,163 @@
 关联结构可视化
 =============================
 
-即将上线！
+.. hint::
 
-.. Basic Usages
-.. --------------
-.. init a structure, call the draw method, and plt.show(), and plt.savefig().
+    - 作者: 张欣炜
+    - 翻译：颜杰龙
+    - 校对: `丰一帆 <https://fengyifan.site/>`_
 
+Basic Usages
+--------------
+DHG provides a simple interface to visualize the correlation structures:
+
+1. Create a structure object (*i.e.*, :py:class:`dhg.Graph`, :py:class:`dhg.BiGraph`, :py:class:`dhg.DiGraph`, and :py:class:`dhg.Hypergraph`);
+2. Call the ``draw()`` method of the object;
+3. Call ``plt.show()`` to show the figure or ``plt.savefig()`` to save the figure.
+
+.. note:: The ``plt`` is short for ``matplotlib.pyplot`` module.
+
+
+Visualization of Graph
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../_static/img/vis_graph.png
+    :align: center
+    :alt: Visualization of Graph
+    :height: 400px
+
+
+.. code-block:: python
+
+    >>> import matplotlib.pyplot as plt
+    >>> from dhg.random import graph_Gnm
+    >>> g = graph_Gnm(10, 12)
+    >>> g.draw()
+    >>> plt.show()
+
+
+Visualization of Directed Graph
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../_static/img/vis_digraph.png
+    :align: center
+    :alt: Visualization of Directed Graph
+    :height: 400px
+
+.. code-block:: python
+
+    >>> import matplotlib.pyplot as plt
+    >>> from dhg.random import digraph_Gnm
+    >>> g = digraph_Gnm(12, 18)
+    >>> g.draw()
+    >>> plt.show()
+
+
+Visualization of Bipartite Graph
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. image:: ../_static/img/vis_bigraph.png
+    :align: center
+    :alt: Visualization of Bipartite Graph
+    :height: 400px
+
+.. code-block:: python
+
+    >>> import matplotlib.pyplot as plt
+    >>> from dhg.random import bigraph_Gnm
+    >>> g = bigraph_Gnm(30, 40, 20)
+    >>> g.draw()
+    >>> plt.show()
+
+
+Visualization of Hypergraph
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../_static/img/vis_hypergraph.png
+    :align: center
+    :alt: Visualization of Hypergraph
+    :height: 400px
+
+.. code-block:: python
+
+    >>> import matplotlib.pyplot as plt
+    >>> from dhg.random import hypergraph_Gnm
+    >>> hg = hypergraph_Gnm(10, 8, method='low_order_first')
+    >>> hg.draw()
+    >>> plt.show()
+
+
+
+Advanced Usages
+---------------------
+
+Customize Labels
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The labels of the vertices could be customized by the ``v_label`` argument. The ``v_label`` could be a list of strings. The labels of the vertices are the strings in the list.
+For example, the following code shows how to customize the labels of the vertices of a graph.
+If the ``v_label`` is not specified, no labels will be shown in the figure.
+The ``font_size`` argument for ``dhg.Graph``, ``dhg.DiGraph``, and ``dhg.Hypergraph``, as well as ``u_font_size`` and ``v_font_size`` for ``dhg.BiGraph`` is used to specify the relative size of the font of the labels, and the default value is ``1.0``.
+The ``font_family`` argument is used to specify the font family of the labels, and the default value is ``'sans-serif'``.
+
+.. code-block:: python
+
+    >>> import matplotlib.pyplot as plt
+    >>> from dhg.random import graph_Gnm
+    >>> g = graph_Gnm(10, 12)
+    >>> labels = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J']
+    >>> g.draw(v_label=labels, font_size=1.5, font_family='serif')
+    >>> plt.show()
+
+.. image:: ../_static/img/custom_label.png
+    :align: center
+    :alt: Customize label
+    :height: 400px
+
+
+Customize Colors
+^^^^^^^^^^^^^^^^^^^^^^^^^
+For ``dhg.Graph``, ``dhg.DiGraph``, and ``dhg.Hypergraph``, the colors of the vertices could be customized by the ``v_color`` argument and the colors of the edges could be customized by the ``e_color`` argument. While for ``dhg.BiGraph``, the colors of the vertices in :math:`\mathcal{U}` could be customized by the ``u_color`` argument and the colors of the vertices in  :math:`\mathcal{V}` could be customized by the ``v_color`` argument.  Both the ``v_color``, ``u_color``, and ``e_color`` could be a string or list of strings. If a string is provided, all the vertices or edges will be colored by the string. If a list of strings is provided, the colors of the vertices or edges are the strings in the list. For example, the following code shows how to customize the colors of the vertices and edges of a hypergraph.
+
+.. code-block:: python
+
+    >>> import matplotlib.pyplot as plt
+    >>> from dhg.random import hypergraph_Gnm
+    >>> hg = hypergraph_Gnm(10, 8, method='low_order_first')
+    >>> hg.draw(v_color='cyan', e_color='grey')
+    >>> plt.show()
+
+.. image:: ../_static/img/custom_color.png
+    :align: center
+    :alt: Customize color
+    :height: 400px
+
+
+Customize Sizes
+^^^^^^^^^^^^^^^^^^^^^^^^^
+For ``dhg.Graph``, ``dhg.DiGraph``, and ``dhg.Hypergraph``, the sizes of the vertices could be customized by the ``v_size`` argument and the sizes of the edges could be customized by the ``e_size`` argument. While for ``dhg.BiGraph``, the sizes of the vertices in :math:`\mathcal{U}` could be customized by the ``u_size`` argument and the sizes of the vertices in  :math:`\mathcal{V}` could be customized by the ``v_size`` argument.  Both the ``v_size``, ``u_size``, and ``e_size`` could be a float or list of float. If a float is provided, all the vertices or edges will be sized by the float. If a list of floats is provided, the sizes of the vertices or edges are the floats in the list. ``v_line_width`` represents the width of the surrounding line of the vertices. ``e_line_width`` represents the width of the line of the edges.
+All of the sizes above represent the relative size, and the default values are ``1.0``. For example, the following code shows how to customize the sizes of the vertices and edges of a hypergraph.
+
+.. code-block:: python
+
+    >>> import matplotlib.pyplot as plt
+    >>> from dhg.random import graph_Gnm
+    >>> g = graph_Gnm(10, 12)
+    >>> g.draw(v_size=1.5, v_line_width=1.5, e_line_width=1.5)
+    >>> plt.show()
+
+.. image:: ../_static/img/custom_size.png
+    :align: center
+    :alt: Customize size
+    :height: 400px
+
+
+
+Customize Layout
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The layout of the structures is based on the modified directed-force layout algorithm. There are four forces to determine the position of the nodes, *i.e.*, node attraction force :math:`f_{na}`, node repulsion force :math:`f_{nr}`, edge repulsion force :math:`f_{er}`, and the center force :math:`f_c`. :math:`f_{na}` is the spring force which attracts the adjacent nodes. :math:`f_{nr}` is used to repel the nodes from each other. :math:`f_{er}` is used to repel the hyperedges from each other, which only make sense for hypergraph visualization. :math:`f_c` is used to attract the nodes to the center (two centers for the bipartite graphs).
+The strength of the forces could be customized by ``forces`` argument, which is a dictionary with the keys ``Simulator.NODE_ATTRACTION``, ``Simulator.NODE_REPULSION``, ``Simulator.EDGE_REPULSION``, and ``Simulator.CENTER_GRAVITY``. The default values of the forces are ``1.0``.
 
-.. Advanced Usages
-.. ---------------------
 
 .. different style, change size, change color, change opacity
 
@@ -28,6 +176,3 @@
 
 .. Hypergraph
 .. ~~~~~~~~~~~~~~~~~~
-
-
-
