Update permutation tree/block docstrings (#157)

* perm tree docs

* base docstrings

hyppo/independence/base.py

@@ -57,6 +57,14 @@ def test(self, x, y, reps=1000, workers=1, is_distsim=True, perm_blocks=None):
             recursively partition samples based on unique labels. Groups at
             each partition are exchangeable under a permutation but remain
             fixed if label is negative.
+        perm_blocks : ndarray, optional (default None)
+            Defines blocks of exchangeable samples during the permutation test.
+            If None, all samples can be permuted with one another. Requires `n`
+            rows. At each column, samples with matching column value are
+            recursively partitioned into blocks of samples. Within each final
+            block, samples are exchangeable. Blocks of samples from the same
+            partition are also exchangeable between one another. If a column
+            value is negative, that block is fixed and cannot be exchanged.
 
         Returns
         -------

hyppo/independence/dcorr.py

@@ -157,11 +157,14 @@ def test(self, x, y, reps=1000, workers=1, auto=True, bias=False, perm_blocks=No
             is greater than 20. If True, and sample size is greater than 20, a fast
             chi2 approximation will be run. Parameters ``reps`` and ``workers`` are
             irrelevant in this case.
-        perm_blocks : list or ndarray, optional
-            Provides hierarchy of dependencies to restrict permutations. Columns
-            provide labels for each sample and recursively partition. Groups at
-            each partition are exchangeable under a permutation but remain
-            fixed if label is negative.
+        perm_blocks : ndarray, optional (default None)
+            Defines blocks of exchangeable samples during the permutation test.
+            If None, all samples can be permuted with one another. Requires `n`
+            rows. At each column, samples with matching column value are
+            recursively partitioned into blocks of samples. Within each final
+            block, samples are exchangeable. Blocks of samples from the same
+            partition are also exchangeable between one another. If a column
+            value is negative, that block is fixed and cannot be exchanged.
 
         Returns
         -------

hyppo/tools/common.py

@@ -417,6 +417,15 @@ def perm_test(calc_stat, x, y, reps=1000, workers=1, is_distsim=True, perm_block
     is_distsim : bool, optional (default: True)
         Whether or not `x` and `y` are distance or similarity matrices. Changes the
         permutation style of `y`.
+    perm_blocks : ndarray, optional (default None)
+        Defines blocks of exchangeable samples during the permutation test.
+        If None, all samples can be permuted with one another. Requires `n`
+        rows. Constructs a tree graph with all samples initially at
+        the root node. Each column partitions samples from the same leaf with 
+        shared column label into a child of that leaf. During the permutation
+        test, samples within the same final leaf node are exchangeable
+        and blocks of samples with a common parent node are exchangeable. If a
+        column value is negative, the resulting block is unexchangeable.
 
     Returns
     -------