Docs

demo_notebooks/advanced/01-custom_live_plot.ipynb

@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 01 Example - Custom Live Plot"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -30,6 +37,13 @@
     "import matplotlib.pyplot as plt"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup devices"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 2,
@@ -43,6 +57,13 @@
     "devices.v3 = ps.TestVoltage() # Device 3"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Define a measure function"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 8,
@@ -68,6 +89,13 @@
     "    return d"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Define Plot Function"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 15,
@@ -86,6 +114,13 @@
     "    "
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Experiments"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 16,

docs/source/advanced/advanced_notebooks.rst

@@ -0,0 +1,10 @@
+Demo Notebooks
+==============
+
+You can find demo notebooks for advanced examples on how to use pyscan
+
+.. toctree::
+    :maxdepth: 1
+
+    demo_notebooks/01-custom_live_plot
+    demo_notebooks/02-multi_live_plot

docs/source/advanced/demo_notebooks/01-custom_live_plot.nblink

@@ -0,0 +1,3 @@
+{
+"path": "../../../../demo_notebooks/advanced/01-custom_live_plot.ipynb"
+}

docs/source/advanced/demo_notebooks/02-multi_live_plot.nblink

@@ -0,0 +1,3 @@
+{
+"path": "../../../../demo_notebooks/advanced/02-multi_live_plot.ipynb"
+}

docs/source/advanced_usage.rst

@@ -5,4 +5,12 @@ Advanced Usage
    :maxdepth: 2
 
    advanced/writing_a_driver
-   advanced/nested_experiments
+   advanced/nested_experiments
+
+Demo Notebooks
+==============
+
+.. toctree::
+   :maxdepth: 2
+
+   advanced/advanced_notebooks

docs/source/api_index.rst

@@ -2,7 +2,7 @@ API
 ===
 
 .. toctree::
-	:maxdepth: 3
+	:maxdepth: 4
 
 	api/general
 	api/measurement

docs/source/basics/installation.md

@@ -20,9 +20,11 @@ git clone https://github.com/sandialabs/pyscan
 3. Install pyscan with
 
 ```
-pip install .
+pip install -e .
 ```
 
+The `-e` makes the package editable, so that if you make modifications to your drivers, for example, you don't need to reinstall the package. This is the recommended method of installation since pyscan is largely intended to be modified when you add drivers for new instruments.
+
 ## Additional Requirements
 
 Some instruments require extra installations in order to use them. For example, Ocean Optics (now known as Ocean Insight) spectrometers require the python package `seabreeze`.  Thorlabs drivers may also require the installation of proprietary .dll files available on their website by installing Thorlabs Kinesis.

docs/source/conf.py

@@ -83,6 +83,7 @@
     # "collapse_navigation": not is_release_build,
     "show_prev_next": True,
     "navbar_align": "left",
+    "show_toc_level": 2,
     # social media links
     "icon_links": [
         {
@@ -91,7 +92,6 @@
             "icon": "fab fa-github-square",
         }
     ],
-    "primary_sidebar_end": [],
     "use_edit_page_button": True,
 }
 
@@ -103,9 +103,3 @@
     "github_repo": "https://github.com/sandialabs/pyscan",
     "github_version": "main",
 }
-
-html_sidebars = {
-    # default is
-    # "**": ["sidebar-nav-bs", "sidebar-ethical-ads"],
-    "**": ["sidebar-nav-bs"]
-}

pyscan/__init__.py

@@ -1,5 +1,5 @@
+from pyscan.general import *
 from pyscan.measurement import *
 from pyscan.drivers import *
-from pyscan.general import *
 from pyscan.plotting import *
 from pyscan.drivers.testing import *

pyscan/general/get_pyscan_version.py

@@ -3,9 +3,9 @@
 
 
 # function that gets the overarching version of pyscan from VERSION.json
-def get_pyscan_version(path="../../VERSION.json"):
+def get_pyscan_version(path="VERSION.json"):
     base_dir = os.path.dirname(os.path.abspath(__file__))
-    path = os.path.join(base_dir, path)
+    path = os.path.join(base_dir, os.pardir, os.pardir, path)
     with open(path) as version_file:
         version = json.load(version_file)['version']
         if type(version) is str:

pyscan/measurement/experiment.py

@@ -27,7 +27,6 @@ class Experiment(AbstractExperiment):
         The path to save the data, defaults to './backup'
     verbose: bool, optional
         Indicates whether to print status updates, defaults to `False`
-
     '''
 
     def __init__(self, runinfo, devices, data_dir=None, verbose=False, time=False):

pyscan/measurement/run_info.py

@@ -63,7 +63,10 @@ def __init__(self):
         self.average_d = -1
 
         self.verbose = False
-        self._pyscan_version = get_pyscan_version()
+        try:
+            self._pyscan_version = get_pyscan_version()
+        except:
+            pass
 
     def check(self):
         '''Checks to see if runinfo is properly formatted. Called by Experiment object's `run()` methods.

pyscan/plotting/__init__.py

@@ -1,6 +1,7 @@
 # Methods
 from .basic_plots import *
 from .oscilloscope import oscilloscope
+from .live_plot import multi_live_plot
 
 # Objects
 from .jupyter_tools import JupyterTools

pyscan/plotting/live_plot.py

@@ -24,7 +24,6 @@ def live_plot(plotting_function, dt=1):
     '''
 
     def live_plot_function(expt=None, *arg, **kwarg):
-
         while (expt.runinfo.running is True and len(expt.runinfo.measured) < 1):
             sleep(1)
 
@@ -49,3 +48,111 @@ def live_plot_function(expt=None, *arg, **kwarg):
         display.clear_output(wait=True)
 
     return live_plot_function
+
+
+def multi_live_plot(plotting_functions, subplot_locators=None, projections=None, nrows=1, ncols=1,
+                    subplot_kw={}, dt=1):
+    '''
+    Generates a function that executes all plotting_function provided while data
+    is still being taken in Jupyter notebooks. Used by the live plotting
+    functions such as :func:`~pyscan.plotting.basicplots.live_plot2D`.
+
+    Parameters
+    ----------
+    plotting_functions : list
+        list of plotting functions to be refreshed. Each function must take exactly
+        two parameters: expt and ax. The function should take data from expt and plot
+        to a matplotlib axis object.
+    subplot_locators : list, optional
+        list of subplot locators in accordance with matplotlib subplot formatted as
+        A 3-digit integer or a tuple with three numbers (nrows, ncols, index).
+        If omitted, then plotting functions will occupy the axes object according to
+        their index position.
+    projections: list, optional
+        list of projections such as None, '3d', 'polar', according to each plotting function.
+        If ommitted, all plots default to 2d.
+    nrows : int, optional
+        How many rows to add to the multiplot. Only used if subplot_locators are not provided.
+    ncols : int, optional
+        How many cols to add to the multiplot. Only used if subplot_locators are not provided.
+    subplot_kw : dict
+        Dict with keywords passed to matplotlib's `add_subplot` call used to create each subplot.
+    dt : float
+        Time in s between refreshes
+
+    Returns
+    -------
+    func : function
+        Its mandatory parameter is list of experiments in the same order as the plotting_functions as
+        defined in the multi_live_plot function. Keyword arguments can be provided and accessed by the
+        plotting_functions as well to further customize plots.
+
+    '''
+
+    # check if subplot_locators was specified
+    if not subplot_locators:
+        # check if n_cols and n_rows accomodates all of the plotting_functions
+        total_axes = nrows * ncols
+        if len(plotting_functions) > total_axes:
+            raise ValueError(f"not enough plots based on {nrows} nrows and {ncols} ncols to accomodate "
+                             + f"{len(plotting_functions)} plotting_functions.")
+    else:
+        # check plotting functions is same length as subplot locators
+        if not len(plotting_functions) == len(subplot_locators):
+            raise ValueError("subplot_locators must be the same length as plotting_functions")
+
+    # check if projections was specified
+    if projections:
+        # check plotting functions is same length as proejctions
+        if not len(plotting_functions) == len(projections):
+            raise ValueError("projections must be the same length as plotting_functions")
+
+    def live_plot_function(expt, *arg, **kwarg):
+        while (expt.runinfo.running is True and len(expt.runinfo.measured) < 1):
+            sleep(1)
+
+        fig = plt.figure(layout="constrained")
+        plt.ion()
+
+        def plot():
+            if subplot_locators:
+                for i, func in enumerate(plotting_functions):
+                    subplot_locator = subplot_locators[i]
+                    if projections:
+                        projection = projections[i]
+                    else:
+                        projection = None
+                    # check if subplot locator is int or tuple
+                    if isinstance(subplot_locator, int):
+                        ax = fig.add_subplot(subplot_locator, projection=projection, **subplot_kw)
+                    elif isinstance(subplot_locator, tuple):
+                        ax = fig.add_subplot(*subplot_locator, projection=projection, **subplot_kw)
+                    func(expt, ax, *arg, **kwarg)
+            else:
+                for i, func in enumerate(plotting_functions):
+                    if projections:
+                        projection = projections[i]
+                    else:
+                        projection = None
+                    ax = fig.add_subplot(nrows, ncols, i + 1, projection=projection, **subplot_kw)
+                    func(expt, ax, *arg, **kwarg)
+            plt.tight_layout()
+
+        while expt.runinfo.running:
+            sleep(dt)
+
+            plt.clf()
+
+            plot()
+
+            display.display(plt.gcf())
+            display.clear_output(wait=True)
+
+        plt.clf()
+
+        plot()
+
+        display.display(plt.gcf())
+        display.clear_output(wait=True)
+
+    return live_plot_function

pyscan/plotting/plot_generator.py

@@ -142,8 +142,16 @@ def get_data(self):
         if (self.d == 2) and (self.data.ndim > 2):
             if self.index3D is None:
                 self.index3D = 0
-            self.data_name = self.data_name + '[{}/{}]'.format(self.index3D, self.data.shape[2])
-            self.data = self.data[:, :, self.index3D]
+                # take the latest level if there are three scans and point data
+                if self.expt.runinfo.ndim == 3:
+                    # get latest row that is being filled (i.e. first data point is not 0)
+                    for i in range(self.data.shape[2]):
+                        if self.data[0, 0, i]:
+                            self.index3D = i
+                else:
+                    self.index3D = 0
+            self.data_name = self.data_name + '[{}/{}]'.format(self.index3D + 1, self.data.shape[2])
+            self.data = self.data.T[self.index3D].T
 
     def get_title(self):
         '''