Repository: physiopy/phys2bids

Issue:
Update docstrings in viz.py
<!--- Provide a general summary of the issue in the Title above -->

## Detailed Description
<!--- Provide a detailed description of the change or addition you are proposing -->
At the moment, the docstring of the functions in `viz.py` are either outdated (after #153) or missing (for `plot_all`).

## Context / Motivation
<!--- Why is this change important to you? How would you use it? -->
<!--- How can it benefit other users? -->
We should update the docstrings for both users and developers.

## Possible Implementation
<!--- Not obligatory, but suggest an idea for implementing addition or change -->
<!--- If you already have worked on the idea, please share a link to the branch in your forked project -->
@vinferrer, as you are the main author of the `viz.py` function, could you tackle this issue?

Comments:

Patch:
diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index 4bf09d1..c3b3ec7 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -254,7 +254,8 @@ def phys2bids(filename, info=False, indir='.', outdir='.', heur_file=None,
     phys_in.print_info(filename)
     # #!# Here the function viz.plot_channel should be called
     if chplot != '' or info:
-        viz.plot_all(phys_in, infile, chplot)
+        viz.plot_all(phys_in.ch_name, phys_in.timeseries, phys_in.units,
+                     phys_in.freq, infile, chplot)
     # If only info were asked, end here.
     if info:
         return
diff --git a/phys2bids/viz.py b/phys2bids/viz.py
index 4fb6970..d925f6c 100644
--- a/phys2bids/viz.py
+++ b/phys2bids/viz.py
@@ -14,8 +14,12 @@ FIGSIZE = (18, 10)
 def plot_trigger(time, trigger, fileprefix, tr, thr, num_timepoints_expected,
                  filename, figsize=FIGSIZE, dpi=SET_DPI):
     """
-    Produces a textfile of the specified extension `ext`,
-    containing the given content `text`.
+    Produces a figure with three plots:
+    1. Plots the triggers in blue, a block in orange that indicates
+    the time from the first trigger to the last, and a red line showing
+    the threshold used for trigger detection
+    2. Same plot but showing only the intial trigger
+    3. Same plot but showing only the intial trigger
 
     Parameters
     ----------
@@ -26,15 +30,19 @@ def plot_trigger(time, trigger, fileprefix, tr, thr, num_timepoints_expected,
     fileprefix: str or path
         A string representing a file name or a fullpath
         to a file, WITHOUT extension
+    tr: float
+        Repetition time
+    thr: float
+        Threshold used to detect the number of triggers
+    num_timepoints_expected: int
+        Number of timepoints expected by the user
     filename: string
         name of the original file
-    options: argparse object
-        The object produced by `get_parser` in `cli.run.py`
-    figsize: tuple
-        Desired size of the figure (see `matplotlib`),
+    figsize: tuple or list of floats
+        Size of the figure expressed as (size_x, size_y),
         Default is {FIGSIZE}
     dpi: int
-        Desired DPI of the figure (see `matplotlib`),
+        Desired DPI of the figure,
         Default is {SET_DPI}
 
     Notes
@@ -42,6 +50,11 @@ def plot_trigger(time, trigger, fileprefix, tr, thr, num_timepoints_expected,
     Outcome:
     fileprefix + _trigger_time.png:
         Creates new plot `fileprefix_trigger_time.png`.
+
+    See Also
+    --------
+    https://phys2bids.readthedocs.io/en/latest/howto.html
+    matplotlib.pyploy.figsize
     """
 
     def time2ntr(x):
@@ -114,19 +127,55 @@ def plot_trigger(time, trigger, fileprefix, tr, thr, num_timepoints_expected,
     plt.close()
 
 
-def plot_all(phys_in, infile, outfile='', dpi=SET_DPI, size=FIGSIZE):
-    ch_num = len(phys_in.ch_name)  # get number of channels:
+def plot_all(ch_name, timeseries, units, freq, infile, outfile='', dpi=SET_DPI, size=FIGSIZE):
+    """
+    Plots all the channels for visualizations and saves them in outfile
+
+    Parameters
+    ----------
+    ch_name: (ch) list of strings
+        List of names of the channels - can be the header of the columns
+        in the output files.
+    timeseries: (ch, [tps]) list
+        List of numpy 1d arrays - one for channel, plus one for time.
+        Time channel has to be the first, trigger the second.
+        Contains all the timeseries recorded.
+    units: (ch) list of strings
+        List of the units of the channels.
+    freq: (ch) list of floats
+        List of floats - one per channel.
+        Contains all the frequencies of the recorded channel.
+    infile: string
+        name of the input file to phys2bids
+    outfile: string
+        path of the output plot
+    dpi: int
+        Desired DPI of the figure,
+        Default is {SET_DPI}
+    figsize: tuple or list of floats
+        Size of the figure expressed as (size_x, size_y),
+        Default is {FIGSIZE}
+    -----
+    outcome:
+        Creates new plot with path specified in outfile.
+
+    See Also
+    --------
+    https://phys2bids.readthedocs.io/en/latest/howto.html
+    matplotlib.pyploy.figsize
+    """
+    ch_num = len(ch_name)  # get number of channels:
     fig, ax = plt.subplots(ch_num - 1, 1, figsize=size, sharex=True)
-    time = phys_in.timeseries[0]  # assume time is first channel
+    time = timeseries[0]  # assume time is first channel
     fig.suptitle(os.path.basename(infile))
-    for row, timeser in enumerate(phys_in.timeseries[1:]):
+    for row, timeser in enumerate(timeseries[1:]):
         if timeser.shape != time.shape:
             time_old = np.linspace(0, time[-1], num=timeser.shape[0])
             timeser = np.interp(time, time_old, timeser)
         ax[row].plot(time, timeser)
-        ax[row].set_title(f' Channel {row + 1}: {phys_in.ch_name[row + 1]}')
-        ax[row].set_ylabel(phys_in.units[row + 1])
-        ax[row].xlim = 30 * 60 * phys_in.freq[0]  # maximum display of half an hour
+        ax[row].set_title(f' Channel {row + 1}: {ch_name[row + 1]}')
+        ax[row].set_ylabel(units[row + 1])
+        ax[row].xlim = 30 * 60 * freq[0]  # maximum display of half an hour
         ax[row].grid()
     ax[row].set_xlabel("seconds")
     if outfile == '':


Test patch:
diff --git a/phys2bids/tests/test_viz.py b/phys2bids/tests/test_viz.py
index edc8132..65b444a 100644
--- a/phys2bids/tests/test_viz.py
+++ b/phys2bids/tests/test_viz.py
@@ -9,7 +9,8 @@ def test_plot_all(samefreq_full_acq_file):
     test_path, test_filename = os.path.split(samefreq_full_acq_file)
     phys_obj = acq.populate_phys_input(samefreq_full_acq_file, chtrig)
     out = os.path.join(test_path, 'Test_belt_pulse_samefreq.png')
-    viz.plot_all(phys_obj, test_filename, outfile=out)
+    viz.plot_all(phys_obj.ch_name, phys_obj.timeseries, phys_obj.units,
+                 phys_obj.freq, test_filename, outfile=out)
     assert os.path.isfile(out)