Modify view_corr_mat in visualisation commands and Update the introdu…

…ction page in docs (#108)

* Add documentation to the introduction page, Getting started section

* Modify view_corr_mat in visualisation commands to accept corr_mat as DataFrame object or as PathToFile or as numpy.array

* Check that corr_mat is n x n (square) matrix, otherwise raise Error

docs/source/introduction.rst

@@ -20,10 +20,25 @@ You can install scona directly from the GitHub repository::
 
 If you want to edit scona it's recommended that you pass the ``-e`` flag to ``pip`` to install the package editably.
 
+Getting Started
+---------------
+
+We have automatically generated `docstring <https://github.com/WhitakerLab/scona/blob/master/DEVELOPMENT_GUIDE.md#writing-docstrings>`_ documentation and here's how to navigate to it.
+
+See all docs organized in the alphabetical order:
+    * :ref:`genindex`
+
+See the structure of the package:
+    * :ref:`modindex`
+
+See the submodules page:
+    * :ref:`ref-subpackages-label`
+
+| Besides, you can type any function into the **search bar** and come up with some results.
+| Alongside this documentation scona has some jupyter notebook `tutorials <https://github.com/WhitakerLab/scona/tree/master/tutorials>`_.
+
 Finding Help
 ------------
 If you have questions or want to get in touch, you can join our `gitter lobby <https://gitter.im/WhitakerLab/BrainNetworksInPython>`_, tweet `@Whitaker_Lab <https://twitter.com/Whitaker_Lab>`_ or email Isla at [email protected].
 
-Getting Started
----------------
-Alongside this documentation scona has some jupyter notebook `tutorials <https://github.com/WhitakerLab/scona/tree/master/tutorials>`_.
+

docs/source/scona.rst

@@ -1,6 +1,8 @@
 scona package
 =============================
 
+.. _ref-subpackages-label:
+
 Subpackages
 -----------
 

scona/scripts/visualisation_commands.py

@@ -54,22 +54,56 @@ def rescale(fname, suff='png'):
     # And you're done!
 
 
-def view_corr_mat(corr_mat_file,
+def view_corr_mat(corr_mat,
                   output_name,
                   cmap_name='RdBu_r',
                   cost=None,
                   bin=False):
-    ''' This is a visualisation tool for correlation matrices'''
+    '''
+    This is a visualisation tool for correlation matrices
+
+    Parameters
+    ----------
+    corr_mat : :class:`str` or :class:`pandas.DataFrame` or :class:`numpy.array`
+        corr_mat could be:
+
+        - a string object - Path to the File, containing the matrix; ``Note`` loading the corr_mat from file is only possible if all data values are float (or integers). Please do not include column or row labels in the file.
+
+        - or a pandas.DataFrame object to represent a correlation matrix;
+
+        - or a numpy.array representing a correlation matrix;
+    output_name : :class:`str`
+        the name of the file you want to save your visualization
+        of correlation matrix to in.
+    cmap_name : string or Colormap, optional
+        A Colormap instance or registered colormap name.
+        The colormap maps scalar data to colors. It is ignored for RGB(A) data.
+        Defaults to 'RdBu_r'.
 
-    # Read in the data
-    M = np.loadtxt(corr_mat_file)
+    Returns
+    -------
+        The visualization of the correlation matrix is saved in the file.
+
+    '''
 
     # If cost is given then roughly threshold at that cost.
     # NOTE - this is not actually the EXACT network that you're analysing
     # because it doesn't include the minimum spanning tree. But it will give
     # you a good sense of the network structure.
     # #GoodEnough ;)
 
+    if isinstance(corr_mat, str):
+        M = np.loadtxt(corr_mat)                  # Read in the data
+    elif isinstance(corr_mat, pd.DataFrame):
+        M = corr_mat.to_numpy()                   # Convert the DataFrame to a NumPy array
+    elif isinstance(corr_mat, np.ndarray):
+        M = corr_mat                              # support numpy array as input to the function
+    else:
+        raise TypeError("corr_mat argument must be 1) a path to the file containing the matrix or 2) pandas.DataFrame object or 3) numpy.array")
+
+    if M.shape[0] != M.shape[1]:
+        raise ValueError("The correlation matrix must be n x n, where n is the number of nodes")
+
     if cost:
         thr = np.percentile(M.reshape(-1), 100-cost)
         M[M<thr] = 0