Added example for concat method (#1037)

* Added example for concat method

* Changes to changelog

* added example of concat over chain/draw

CHANGELOG.md

@@ -32,11 +32,10 @@
 ### Documentation
 * Updated `InferenceData` schema specification (`log_likelihood`,
   `predictions` and `predictions_constant_data` groups)
-*  Clarify the usage of "plot_joint" (#1001)
-*  Added the API link of function to examples (#1013)
-* Clarify the usage of "plot_joint" (#1001)
+* Clarify the usage of `plot_joint` (#1001)
 * Added the API link of function to examples (#1013)
 * Updated PyStan_schema_example to include example of out-of-sample prediction (#1032)
+* Added example for `concat` method (#1037)
 
 
 ## v0.6.1 (2019 Dec 28)

arviz/data/inference_data.py

@@ -276,6 +276,49 @@ def concat(*args, dim=None, copy=True, inplace=False, reset_dim=True):
     InferenceData
         A new InferenceData object by default.
         When `inplace==True` merge args to first arg and return `None`
+
+    Examples
+    --------
+    Use ``concat`` method to concatenate InferenceData objects. This will concatenates over
+    unique groups by default. We first create an ``InferenceData`` object:
+
+    .. ipython::
+
+        In [1]: import arviz as az
+           ...: import numpy as np
+           ...: data = {
+           ...:     "a": (["chain", "draw", "a_dim"], np.random.normal(size=(4, 100, 3))),
+           ...:     "b": (["chain", "draw"], np.random.normal(size=(4, 100))),
+           ...: }
+           ...: coords = {"a_dim": ["x", "y", "z"]}
+           ...: dataA = az.from_dict(data, coords=coords, dims={"a": ["a_dim"]})
+           ...: dataA
+
+    We have created an ``InferenceData`` object with default group 'posterior'. Now, we will
+    create another ``InferenceData`` object:
+
+    .. ipython::
+
+        In [1]: dataB = az.from_dict(prior=data, coords=coords, dims={"a": ["a_dim"]})
+           ...: dataB
+
+    We have created another ``InferenceData`` object with group 'prior'. Now, we will concatenate
+    these two ``InferenceData`` objects:
+
+    .. ipython::
+
+        In [1]: az.concat(dataA, dataB)
+
+    Now, we will concatenate over chain (or draw). It requires identical groups and variables.
+    Here we are concatenating two identical ``InferenceData`` objects over dimension chain:
+
+    .. ipython::
+
+        In [1]: az.concat(dataA, dataA, dim="chain")
+
+    It will create an ``InferenceData`` with the original group 'posterior'. In similar way,
+    we can also concatenate over draws.
+
     """
     # pylint: disable=undefined-loop-variable, too-many-nested-blocks
     if len(args) == 0: