Merge pull request #150 from ianhi/thresholding

More natural behavior for scalar arguments

README.md

@@ -6,66 +6,16 @@
 
 ## Welcome!
 
-mpl_interactions' library provides helpful ways to interact with [Matplotlib](https://matplotlib.org/) plots. A summary of key components can be found below. Fuller narrative, further examples, and more information can be found on [ReadtheDocs](https://mpl-interactions.readthedocs.io/en/latest/#).
+mpl_interactions' library provides helpful ways to interact with [Matplotlib](https://matplotlib.org/) plots. Full narrative documentation and example can be found on [ReadtheDocs](https://mpl-interactions.readthedocs.io/en/stable/#).
 
 <img src=https://raw.githubusercontent.com/ianhi/mpl-interactions/master/docs/_static/images/short-interactive.gif width=45%>  <img src=https://raw.githubusercontent.com/ianhi/mpl-interactions/master/docs/_static/images/heatmap_slicer.gif width=45%>
 
-There are three submodules:
-
-**pyplot**
-
-Control Matplotlib plots using sliders and other widgets to adjust the parameters of the functions you are plotting. If working in a notebook then ipywidgets will be used to make the sliders, otherwise Matplotlib widgets will be used.
-
-This is a different approach to controlling plots with sliders than `ipywidgets.interact` as when using `interact` you are responsible for:
-1. Defining the function to plot `f(x,...) => y`
-2. Handling the plotting logic (`plt.plot`, `fig.cla`, `ax.set_ylim`, etc)
-
-In contrast, with `mpl-interactions` you only need to provide `f(x, ...) => y` and the plotting and updating boilerplate are handled for you.
-
-```python
-x = np.linspace(0,6,100)
-beta = np.linspace(0,5*np.pi)
-def f(x, beta):
-    return np.sin(x*4+beta)
-interactive_plot(f, x=x, beta=beta)
-```
-
-These functions are designed to be used with [ipympl](https://github.com/matplotlib/ipympl), the backend that is designed for use in Jupyter Notebooks. So for optimal performance, make sure you set the backend with `%matplotlib ipympl`. That said, these functions will also work with any interactive backend (e.g. `%matplotlib qt5`).
-
-
-**generic**
-
-Provides ways to interact with Matplotlib that will work outside of a Jupyter Notebook; this should work equally well with any backend.
-1. A very niche (but very cool) way to compare 2D heatmaps
-2. Scroll to zoom
-3. Middle click to pan
-
-**utils**
-
-This module includes utility functions to make things just that little bit easier.
-
-1. `ioff` as a context manager
-
-```python
-from mpl_interactions.utils import ioff
-with ioff:
-    # interactive mode will be off
-    fig = plt.figure()
-    # other stuff
-# interactive mode will be on
-```
-2. `figure` that accepts a scalar for `figsize` (this will scale the default dimensions)
-```python
-from mpl_interactions.utils import figure
-fig = figure(3)
-# the default figsize is [6.4, 4.8], this figure will have figsize = [6.4*3, 4.8*3]
-```
-
-3. `nearest_idx` -- avoid ever having to write `np.argmin(np.abs(arr - value))` again
-
 
 ## Installation
 ```bash
+pip install mpl_interactions["jupyter"] # will install necessary deps for using in jupyter
+
+# for use only outside of jupyter:
 pip install mpl_interactions
 
 # if using jupyterlab
@@ -82,24 +32,6 @@ I use the GitHub [issues](https://github.com/ianhi/mpl-interactions/issues) to k
 
 The fuller narrative documentation can be found on [ReadTheDocs](https://mpl-interactions.readthedocs.io/en/latest/). You may also find it helpful to check out the [examples directory](https://github.com/ianhi/mpl-interactions/tree/master/examples).
 
-
-## Examples with GIFs!
-Tragically, neither GitHub nor the sphinx documentation render the actual moving plots so instead, here are gifs of the functions. The code for these can be found in the notebooks in the examples directory.
-
-
-### interactive_plot
-Easily make a line plot interactive:
-![](docs/_static/images/interactive-plot.gif)
-
-
-### heatmap_slicer
-Compare vertical and horizontal slices across multiple heatmaps:
-![](docs/_static/images/heatmap_slicer.gif)
-
-
-### scrolling zoom + middle click pan
-![](docs/_static/images/zoom-and-pan.gif)
-
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

docs/Contributing.rst

@@ -51,6 +51,13 @@ Also feel free to ask for help/advice on the relevant Github `issue <https://git
 Documentation
 -------------
 
+For the most part the Documentation is generated from the Notebooks in the `examples` folder. So to write new
+examples work in a notebook in the ``examples`` directory. When the docs are generated then they will be
+converted to html via `nbsphinx <https://nbsphinx.readthedocs.io/en/latest/>`_. 
+
+If you are adding a new example then you need to include it in the toctree in ``docs/index.rst``.
+
+
 Following changes to the source files, you can view recent adjustments by building the documentation.
 
 1. Make sure you have installed the requirements for building the documentation:
@@ -69,6 +76,16 @@ Following changes to the source files, you can view recent adjustments by buildi
 
 If you open the ``index.html`` file in your browser you should now be able to see the rendered documentation.
 
+Embedding GIFs
+^^^^^^^^^^^^^^
+
+Unfortunately the interactive plots are not interactive on readthedocs, this is because they require an active
+Python kernel to work. So instead we short gifs or apngs of interacting with the plots and embed them. To accomplish this
+the GIFs are stored in ``docs/_static/images`` and they are automatically embedded when the notebooks are converted to html
+based on the file names in the cell metadata. For example here is the process of setting the metadata of a cell when using JupyterLab.
+
+.. image:: _static/images/how-to-embed-gif.gif
+
 Autobuild the documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/index.rst

@@ -97,6 +97,8 @@ Further discussion of the behavior as a function of backend can be found on the
    examples/mpl-sliders.ipynb
    examples/scatter-selector.ipynb
    examples/animations.ipynb
+   examples/range-sliders.ipynb
+   examples/scalar-arguments.ipynb
    examples/image-segmentation.ipynb
    examples/zoom-factory.ipynb
    examples/heatmap-slicer.ipynb

examples/Lotka-Volterra.ipynb

@@ -38,13 +38,14 @@
     "t = np.linspace(0, 15, 1000)  # time\n",
     "X0 = np.array([10, 5])  # initials conditions: 10 rabbits and 5 foxes\n",
     "\n",
+    "# use `c_` instead of `c` because `c` is an argument to plt.scatter\n",
     "\n",
-    "def f(a, b, c, d):\n",
+    "def f(a, b, c_, d):\n",
     "    def dX_dt(X, t=0):\n",
     "        \"\"\" Return the growth rate of fox and rabbit populations. \"\"\"\n",
     "        rabbits, foxes = X\n",
     "        dRabbit_dt = a * rabbits - b * foxes * rabbits\n",
-    "        dFox_dt = -c * foxes + d * b * rabbits * foxes\n",
+    "        dFox_dt = -c_ * foxes + d * b * rabbits * foxes\n",
     "        return [dRabbit_dt, dFox_dt]\n",
     "\n",
     "    X, _ = integrate.odeint(dX_dt, X0, t, full_output=True)\n",
@@ -70,7 +71,7 @@
    "source": [
     "fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(10, 4.8))\n",
     "controls = iplt.plot(\n",
-    "    f, ax=ax1, a=(0.5, 2), b=(0.1, 3), c=(1, 3), d=(0.1, 2), parametric=True\n",
+    "    f, ax=ax1, a=(0.5, 2), b=(0.1, 3), c_=(1, 3), d=(0.1, 2), parametric=True\n",
     ")\n",
     "ax1.set_xlabel(\"rabbits\")\n",
     "ax1.set_ylabel(\"foxes\")\n",
@@ -118,7 +119,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.8"
+   "version": "3.9.0"
   }
  },
  "nbformat": 4,

examples/Usage-Guide.ipynb

@@ -212,6 +212,34 @@
     "controls = iplt.plot(x, f, tau=(5, 10, 5), beta=(0.25, 1))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Tuples for RangeSliders\n",
+    "\n",
+    "You can create a RangeSlider by passing a tuple prefixed with an \"r\"."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "gif": "usage-rangeslider.apng"
+   },
+   "outputs": [],
+   "source": [
+    "def f_x(min_max, **kwargs):\n",
+    "    # break up the tuple\n",
+    "    min_, max_ = min_max\n",
+    "    return np.linspace(min_, max_, 100)\n",
+    "    # break up the tuple\n",
+    "def f_range(x, tau, **kwargs):\n",
+    "    return np.sin(x*tau)\n",
+    "fig, ax = plt.subplots()\n",
+    "controls = iplt.plot(f_x, f_range, tau=(5, 10, 5), min_max = (\"r\", 0, 10))"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/imshow.ipynb

@@ -99,7 +99,7 @@
    "source": [
     "### vmin and vmax: thresholding an image\n",
     "\n",
-    "You can also pass `vmin` and `vmax` as functions. Additionally you do not need to use a function to provide the image, you can also provide an array"
+    "Here we use the `vmin_vmax` argument along with the syntax for a RangeSlider to easily threshold the image. For more on how to use RangeSliders see [their example page](range-sliders.ipynb). Additionally you do not need to use a function to provide the image, you can also provide an array"
    ]
   },
   {
@@ -113,16 +113,8 @@
     "img = plt.imread(\"https://matplotlib.org/3.3.1/_images/stinkbug.png\")\n",
     "\n",
     "\n",
-    "def vmin(min_, max_):\n",
-    "    return min(min_, max_)\n",
-    "\n",
-    "\n",
-    "def vmax(min_, max_):\n",
-    "    return max(min_, max_)\n",
-    "\n",
-    "\n",
     "fig4, ax4 = plt.subplots()\n",
-    "controls4 = iplt.imshow(img, vmin=vmin, vmax=vmax, min_=(0, 0.7), max_=(0.3, 1))"
+    "controls4 = iplt.imshow(img, vmin_vmax=(\"r\", img.min(), img.max()))"
    ]
   },
   {
@@ -149,7 +141,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.8"
+   "version": "3.9.0"
   }
  },
  "nbformat": 4,

examples/mpl-sliders.ipynb

@@ -133,7 +133,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.9.0"
   }
  },
  "nbformat": 4,