Merge pull request #6 from cdt15/v1.3

V1.3

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 T.Ikeuchi, G.Haraoka, S.Shimizu
+Copyright (c) 2019 T.Ikeuchi, G.Haraoka, W.Kurebayashi, S.Shimizu
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/conf.py

@@ -21,8 +21,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'LiNGAM'
-copyright = '{}, T.Ikeuchi, G.Haraoka, S.Shimizu'.format(datetime.datetime.now().year)
-author = 'T.Ikeuchi, G.Haraoka, S.Shimizu'
+author = 'T.Ikeuchi, G.Haraoka, W.Kurebayashi, S.Shimizu'
+copyright = '{}, {}'.format(datetime.datetime.now().year, author)
 
 import lingam
 version = lingam.__version__

docs/reference/index.rst

@@ -11,6 +11,8 @@ API Reference
     multi_group_direct_lingam
     var_lingam
     varma_lingam
+    longitudinal_lingam
     bootstrap
+    longitudinal_bootstrap
     causal_effect
     utils

docs/reference/longitudinal_bootstrap.rst

@@ -0,0 +1,8 @@
+.. module:: lingam
+
+LongitudinalBootstrapResult
+===========================
+
+.. autoclass:: LongitudinalBootstrapResult
+    :members:
+    :inherited-members:

docs/reference/longitudinal_lingam.rst

@@ -0,0 +1,8 @@
+.. module:: lingam
+
+LongitudinalLiNGAM
+==================
+
+.. autoclass:: LongitudinalLiNGAM
+    :members:
+    :inherited-members:

docs/tutorial.rst

@@ -84,7 +84,7 @@ Then, we call :func:`~lingam.DirectLiNGAM.bootstrap` method instead of :func:`~l
 Causal Directions
 ^^^^^^^^^^^^^^^^^
 
-Since :class:`~lingam.BootstrapResult` object is returned, we can get the ranking of the causal directions extracted by :func:`~lingam.BootstrapResult.get_causal_direction_counts` method. 
+Since :class:`~lingam.BootstrapResult` object is returned, we can get the ranking of the causal directions extracted by :func:`~lingam.BootstrapResult.get_causal_direction_counts` method.
 
 .. code-block:: python
 
@@ -305,7 +305,7 @@ we use lingam package and :func:`~lingam.utils.make_prior_knowledge`:
 .. code-block:: python
 
     import lingam
-    form lingam.utils import make_prior_knowledge
+    from lingam.utils import make_prior_knowledge
 
 First, we create a prior knowledge matrix:
 
@@ -328,6 +328,12 @@ First, we create a prior knowledge matrix:
      [-1  0  1 -1  0 -1]
      [-1  0 -1 -1 -1  0]]
 
+The values of the prior knowledge matrix elements are represented as follows:
+
+* ``0`` : :math:`x_i` does not have a directed path to :math:`x_j`
+* ``1`` : :math:`x_i` has a directed path to :math:`x_j`
+* ``-1`` : No prior knowledge is available to know if either of the two cases above (0 or 1) is true.
+
 Then, if we use a prior knowledge, we set prior knowledge matrix to :class:`~lingam.DirectLiNGAM` object:
 
 .. code-block:: python
@@ -394,7 +400,7 @@ Using the :attr:`~lingam.MultiGroupDirectLiNGAM.causal_order_` property, we can
 
     print(model.causal_order_)
 
-Also, using the :attr:`~lingam.MultiGroupDirectLiNGAM.adjacency_matrices_` property, we can see the adjacency matrix as a result of the causal discovery. 
+Also, using the :attr:`~lingam.MultiGroupDirectLiNGAM.adjacency_matrices_` property, we can see the adjacency matrix as a result of the causal discovery.
 Since :attr:`~lingam.MultiGroupDirectLiNGAM.adjacency_matrices_` property returns a list, we can access the first matrix by indexing as follows:
 
 .. code-block:: python
@@ -495,6 +501,23 @@ In the following example, we estimate the intervention value at variable index 1
 
     Optimal intervention: 7.871
 
+Use a known causal model
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+When using a known causal model, we can specify the adjacency matrix when we create :class:`~lingam.CausalEffect` object.
+
+.. code-block:: python
+
+    m = np.array([[0.0, 0.0, 0.0, 3.0, 0.0, 0.0],
+                  [3.0, 0.0, 2.0, 0.0, 0.0, 0.0],
+                  [0.0, 0.0, 0.0, 6.0, 0.0, 0.0],
+                  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+                  [8.0, 0.0,-1.0, 0.0, 0.0, 0.0],
+                  [4.0, 0.0, 0.0, 0.0, 0.0, 0.0]])
+    
+    ce = lingam.CausalEffect(causal_model=m)
+    effects = ce.estimate_effects_on_prediction(X, target, reg)
+
 For details, see also https://github.com/cdt15/lingam/blob/master/examples/CausalEffect.ipynb
 https://github.com/cdt15/lingam/blob/master/examples/CausalEffect(LassoCV).ipynb
 https://github.com/cdt15/lingam/blob/master/examples/CausalEffect(LogisticRegression).ipynb
@@ -601,7 +624,7 @@ The output of the :attr:`~lingam.VARMALiNGAM.adjacency_matrices_` property is as
        [-0.392,  0.   ,  0.182,  0.   ,  0.   ],
        [ 0.   ,  0.   ,  0.   ,  0.   ,  0.   ],
        [ 0.523, -0.149,  0.   ,  0.   ,  0.   ],
-       [ 0.   ,  0.   ,  0.   ,  0.   ,  0.   ]], 
+       [ 0.   ,  0.   ,  0.   ,  0.   ,  0.   ]],
       [[-0.145, -0.288, -0.418,  0.041,  0.592],
        [-0.324,  0.027,  0.024,  0.231,  0.379],
        [-0.249,  0.191, -0.01 ,  0.136,  0.261],
@@ -620,3 +643,43 @@ For example, we can draw a causal graph by using graphviz as follows:
 
 For details, see also https://github.com/cdt15/lingam/blob/master/examples/VARMALiNGAM.ipynb
 
+LongitudinalLiNGAM
+------------------
+
+We use lingam package:
+
+.. code-block:: python
+
+    import lingam
+
+First, if we use datasets from several time-points, we create a list like this:
+
+.. code-block:: python
+
+    X_list = [X1, X2, X3]
+
+Then, if we want to run Longitudinal-LiNGAM algorithm, we create a :class:`~lingam.LongitudinalLiNGAM` object and call the :func:`~lingam.LongitudinalLiNGAM.fit` method:
+
+.. code-block:: python
+
+    model = lingam.LongitudinalLiNGAM()
+    model.fit(X_list)
+
+Using the :attr:`~lingam.LongitudinalLiNGAM.causal_orders_` property, we can see the causal ordering in time-points as a result of the causal discovery.
+
+.. code-block:: python
+
+    print(model.causal_orders_)
+
+Also, using the :attr:`~lingam.LongitudinalLiNGAM.adjacency_matrices_` property, we can see the adjacency matrix as a result of the causal discovery.
+
+.. code-block:: python
+
+    t = 1
+    print('B(1,1):\n', model.adjacency_matrices_[t, 0])
+    print('B(1,0):\n', model.adjacency_matrices_[t, 1])
+
+    t = 2
+    print('B(2,2):\n', model.adjacency_matrices_[t, 0])
+    print('B(2,1):\n', model.adjacency_matrices_[t, 1])
+