From 9ada3fe07911f70877c884cba5bfc1262926249c Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 28 May 2020 01:49:45 -0400 Subject: [PATCH 1/4] Update documenting_mpl.rst --- doc/devel/documenting_mpl.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 551b25912d8a..d73a28d7ee24 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -121,8 +121,12 @@ You can use the ``O`` variable to set additional options: Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0' html``. -On Windows, options needs to be set as environment variables, e.g. ``set O=-W ---keep-going -j4 & make html``. +On Windows, options needs to be set as environment variables, e.g.: + +.. code-block:: bat + + set O=-W --keep-going -j4 + make html .. _writing-rest-pages: From 28c3b4fd3d62ce9dcc2afb85d07067b8852e9de8 Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 28 May 2020 02:49:14 -0400 Subject: [PATCH 2/4] Update documenting_mpl.rst --- doc/devel/documenting_mpl.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index d73a28d7ee24..abb1dd63e88c 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -111,6 +111,12 @@ it, use .. code-block:: sh make SPHINXOPTS= html + +On Windows the arguments must be at the end of the statement: + +.. code-block:: bat + + make html SPHINXOPTS= You can use the ``O`` variable to set additional options: @@ -121,7 +127,7 @@ You can use the ``O`` variable to set additional options: Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0' html``. -On Windows, options needs to be set as environment variables, e.g.: +On Windows, either use the format shown above or set options as environment variables, e.g.: .. code-block:: bat From bd5d63ab9bb42c0070907a3c48a906c3de79165f Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 21 May 2020 04:35:23 -0400 Subject: [PATCH 3/4] cleaned up idioms, restructured the code example, stripped down sme langauge --- doc/users/interactive.rst | 141 ++++++++++++++++++-------------------- 1 file changed, 65 insertions(+), 76 deletions(-) diff --git a/doc/users/interactive.rst b/doc/users/interactive.rst index 8c10d1250f3a..c1db0db3ba94 100644 --- a/doc/users/interactive.rst +++ b/doc/users/interactive.rst @@ -9,40 +9,41 @@ .. toctree:: -When working with data it is often invaluable to be able to interact -with your plots. In many cases the built in pan/zoom and mouse-location -tools are sufficient, but you can also use the Matplotlib event system -to build customized data exploration tools. +When working with data, interactivity can be invaluable. The pan/zoom and +mouse-location tools built into the Matplotlib GUI windows are often sufficient, but +you can also use the event system to build customized data exploration tools. Matplotlib ships with :ref:`backends ` binding to several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party packages provide bindings to `kivy `__ and `Jupyter Lab -`__. For the figures to be -"live" the GUI event loop will need to be integrated with your prompt. The -simplest way is to use IPython (see :ref:`below `). +`__. For the figures to be interactive, +the GUI event loop will need to be integrated with your interactive prompt. +We recommend using IPython (see :ref:`below `). -The `.pyplot` module provides functions for explicitly creating -Figures that include interactive tools, a toolbar, a tool-tip, and -:ref:`key bindings ` ready to go: +The `.pyplot` module provides functions for explicitly creating figures +that include interactive tools, a toolbar, a tool-tip, and +:ref:`key bindings `: -`.pyplot.figure` +* `.pyplot.figure` Creates a new empty `.figure.Figure` or selects an existing figure -`.pyplot.subplots` +* `.pyplot.subplots` Creates a new `.figure.Figure` and fills it with a grid of `.axes.Axes` `.pyplot` has a notion of "The Current Figure" which can be accessed through `.pyplot.gcf` and a notion of "The Current Axes" accessed through `.pyplot.gca`. Almost all of the functions in `.pyplot` pass through the current `.Figure` / `.axes.Axes` (or create one) as -appropriate. Matplotlib keeps a reference to all of the open figures +appropriate. + +Matplotlib keeps a reference to all of the open figures created this way so they will not be garbage collected. You can close and deregister `.Figure`\s from `.pyplot` individually via `.pyplot.close` or close all open figures via ``plt.close('all')``. -For discussion of how the integration of the event loops and Matplotlib's event -system work under the hood see: + +For more discussion of Matplotlib's event system and integrated event loops, please read: .. toctree:: :maxdepth: 1 @@ -67,54 +68,46 @@ loop is properly integrated with the command line (see .. highlight:: ipython :: - - user@machine:~ $ ipython - Python 3.8.2 (default, Apr 8 2020, 14:31:25) - Type 'copyright', 'credits' or 'license' for more information - IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help. - In [1]: %matplotlib Using matplotlib backend: Qt5Agg In [2]: import matplotlib.pyplot as plt -Calling +Create a new figure window: :: In [3]: fig, ax = plt.subplots() -will pop open a window for you and + +Add a line plot of the data to the window: :: In [4]: ln, = ax.plot(range(5)) -will show your data in the window. If you change something about the -line, for example the color +Change the color of the line from blue to orange: :: In [5]: ln.set_color('orange') -it will be reflected immediately. If you wish to disable this behavior -use +If you wish to disable interactive modification of the plot: :: In [6]: plt.ioff() -and +If you wish to re-enable interactive "live" modification of the plot: :: In [7]: plt.ion() -re-enable it. -With recent versions of ``Matplotlib`` and ``IPython`` it is -sufficient to import `matplotlib.pyplot` and call `.pyplot.ion`, but -using the magic is guaranteed to work regardless of versions. +In recent versions of ``Matplotlib`` and ``IPython``, it is +sufficient to import `matplotlib.pyplot` and call `.pyplot.ion`. +Using the ``%`` magic is guaranteed to work in all versions of ``Matplotlib`` and ``IPython``. .. highlight:: python @@ -146,45 +139,43 @@ Interactive mode controls: - whether created figures are automatically shown - whether changes to artists automatically trigger re-drawing existing figures -- whether `.pyplot.show` returns immediately or after all of the - figures have been closed when given no arguments - +- when `.pyplot.show` exits: immediately, or after all of the figures have been closed if given no arguments -If in interactive mode, then: +Interactive mode: -- newly created figures will be shown immediately -- figures will automatically redraw on change -- pyplot.show will return immediately by default +- newly created figures will be displayed immediately +- figures will automatically redraw when elements are changed +- `pyplot.show` displays the figures and immediately returns to the prompt -If not in interactive mode then: +Not in interactive mode: -- newly created figures and changes to figures will - not be reflected until explicitly asked to be -- pyplot.show runs the GUI event loop and does not return until all of - the plot windows are closed +- newly created figures and changes to figures are not displayed until +`.pyplot.show` is called again or `.pyplot.pause` exits +- `pyplot.show` runs the GUI event loop and does not return until all +the plot windows are closed If you are in non-interactive mode (or created figures while in non-interactive mode) you may need to explicitly call `.pyplot.show` -to bring the windows onto your screen. If you only want to run the -GUI event loop for a fixed amount of time you can use `.pyplot.pause`. -This will both block the progress of your code (as if you had called -`time.sleep`), ensure the current window is shown and if needed -re-drawn, and run the GUI event loop (so the windows are "live" for -interaction) for the specified period of time. - -Being in "interactive mode" is orthogonal to the GUI event loop being -integrated with your command prompt. If you use `pyplot.ion`, but -have not arranged for the event loop integration, your figures will -appear but will not be "live" while the prompt is waiting for input. +to display the windows on your screen. If you only want to run the +GUI event loop for a fixed amount of time, you can use `.pyplot.pause`. +This will block the progress of your code as if you had called +`time.sleep`, ensure the current window is shown and re-drawn if needed, +and run the GUI event loop (so the windows are "live" for +interactive modification) for the specified period of time. + +The GUI event loop being integrated with your command prompt and +the figures being in interactive mode are independent of each other. +If you use `pyplot.ion` but have not arranged for the event loop integration, +your figures will appear but will not be "live" while the prompt is waiting for input. You will not be able to pan/zoom and the figure may not even render (the window might appear black, transparent, or as a snapshot of the desktop under it). Conversely, if you configure the event loop integration, displayed figures will be "live" while waiting for input -at the prompt, regardless of pyplot's "interactive mode". In either -case, the figures will be "live" if you use -``pyplot.show(block=True)``, `.pyplot.pause`, or run the the GUI main -loop in some other way. +at the prompt, regardless of pyplot's "interactive mode". + +The figures will also be "live" if you use ``pyplot.show(block=True)``, +`.pyplot.pause`, or run the the GUI main loop in some other way. .. warning:: @@ -201,7 +192,7 @@ Default UI The windows created by :mod:`~.pyplot` have an interactive toolbar with navigation -buttons and a readout of where the cursor is in dataspace. A number of +buttons and a readout of the data values the cursor is pointing at. A number of helpful keybindings are registered by default. @@ -240,8 +231,7 @@ Preserve aspect ratio hold **CONTROL** when panning/zooming with mo Other Python prompts ==================== -If you can not or do not want to use IPython, interactive mode works -in the vanilla python prompt +Interactive mode works in the default Python prompt: .. sourcecode:: pycon @@ -265,11 +255,11 @@ Jupyter Notebooks / Lab using an interactive backend. The default backend in notebooks, the inline backend, is not. `~ipykernel.pylab.backend_inline` renders the figure once and inserts a static image into the - notebook when the cell is executed. The images are static and can - not be panned / zoomed, take user input, or be updated from other + notebook when the cell is executed. Because the images are static, they + can not be panned / zoomed, take user input, or be updated from other cells. -To get interactive figures in the 'classic' notebook or jupyter lab +To get interactive figures in the 'classic' notebook or Jupyter lab, use the `ipympl `__ backend (must be installed separately) which uses the **ipywidget** framework. If ``ipympl`` is installed use the magic: @@ -280,25 +270,24 @@ If ``ipympl`` is installed use the magic: to select and enable it. -If you only need to use the classic notebook you can use +If you only need to use the classic notebook, you can use .. sourcecode:: ipython %matplotlib notebook -which uses the `.backend_nbagg` backend which ships with Matplotlib. -However nbagg does not work in Jupyter Lab. +which uses the `.backend_nbagg` backend which is installed by Matplotlib; +however, nbagg does not work in Jupyter Lab. -GUIs + jupyter +GUIs + Jupyter ~~~~~~~~~~~~~~ -If you are running your jupyter kernel locally you can use one of the -GUI backends. The process running your kernel will show a GUI window -on your desktop adjacent to your web browser. However if you move -that notebook to a remote server the kernel will try to open the GUI -window on *that* computer. Unless you have arranged to forward the -xserver back to your desktop, you not be able to see or interact with -the figure (if it does not raise an exception outright). +You can also use one of the non-ipympl GUI backends in a Jupyter Notebook. +If you are running your Jupyter kernel locally, the GUI window will spawn on +your desktop adjacent to your web browser. If you run your notebook on a remote server, +the kernel will try to open the GUI window on the remote computer. Unless you have +arranged to forward the xserver back to your desktop, you will not be able to +see or interact with the window. It may also raise an exception. From e6411d4d2a62009a6648ef7782afb8380bbe1f8f Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 21 May 2020 13:44:50 -0400 Subject: [PATCH 4/4] Update doc/users/interactive.rst Co-authored-by: Thomas A Caswell Co-authored-by: David Stansby Co-authored-by: Elliott Sales de Andrade --- doc/users/interactive.rst | 104 +++++++++++++++++++------------------- 1 file changed, 53 insertions(+), 51 deletions(-) diff --git a/doc/users/interactive.rst b/doc/users/interactive.rst index c1db0db3ba94..75101cb3bec7 100644 --- a/doc/users/interactive.rst +++ b/doc/users/interactive.rst @@ -9,38 +9,38 @@ .. toctree:: -When working with data, interactivity can be invaluable. The pan/zoom and -mouse-location tools built into the Matplotlib GUI windows are often sufficient, but +When working with data, interactivity can be invaluable. The pan/zoom and +mouse-location tools built into the Matplotlib GUI windows are often sufficient, but you can also use the event system to build customized data exploration tools. Matplotlib ships with :ref:`backends ` binding to several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party packages provide bindings to `kivy `__ and `Jupyter Lab -`__. For the figures to be interactive, -the GUI event loop will need to be integrated with your interactive prompt. -We recommend using IPython (see :ref:`below `). +`__. For the figures to be responsive to +mouse, keyboard, and paint events, the GUI event loop needs to be integrated +with an interactive prompt. We recommend using IPython (see :ref:`below `). -The `.pyplot` module provides functions for explicitly creating figures +The `.pyplot` module provides functions for explicitly creating figures that include interactive tools, a toolbar, a tool-tip, and :ref:`key bindings `: -* `.pyplot.figure` +`.pyplot.figure` Creates a new empty `.figure.Figure` or selects an existing figure -* `.pyplot.subplots` +`.pyplot.subplots` Creates a new `.figure.Figure` and fills it with a grid of `.axes.Axes` `.pyplot` has a notion of "The Current Figure" which can be accessed through `.pyplot.gcf` and a notion of "The Current Axes" accessed through `.pyplot.gca`. Almost all of the functions in `.pyplot` pass through the current `.Figure` / `.axes.Axes` (or create one) as -appropriate. +appropriate. Matplotlib keeps a reference to all of the open figures -created this way so they will not be garbage collected. You can close -and deregister `.Figure`\s from `.pyplot` individually via -`.pyplot.close` or close all open figures via ``plt.close('all')``. +created via `pyplot.figure` or `pyplot.subplots` so that the figures will not be garbage +collected. `.Figure`\s can be closed and deregistered from `.pyplot` individually via +`.pyplot.close`; all open `.Figure`\s can be closed via ``plt.close('all')``. For more discussion of Matplotlib's event system and integrated event loops, please read: @@ -58,12 +58,14 @@ IPython integration =================== We recommend using IPython for an interactive shell. In addition to -all of its features (improved tab-completion, magics, -multiline editing, etc), it also ensures that the GUI toolkit event -loop is properly integrated with the command line (see -:ref:`cp_integration`). To configure the integration and enable -:ref:`interactive mode ` use the -``%matplotlib`` magic +all of its features (improved tab-completion, magics, multiline editing, etc), +it also ensures that the GUI toolkit event loop is properly integrated +with the command line (see :ref:`cp_integration`). + +In this example, we create and modify a figure via an IPython prompt. +The figure displays in a Qt5Agg GUI window. To configure the integration +and enable :ref:`interactive mode ` use the +``%matplotlib`` magic: .. highlight:: ipython @@ -92,13 +94,13 @@ Change the color of the line from blue to orange: In [5]: ln.set_color('orange') -If you wish to disable interactive modification of the plot: +If you wish to disable automatic redrawing of the plot: :: In [6]: plt.ioff() -If you wish to re-enable interactive "live" modification of the plot: +If you wish to re-enable automatic redrawing of the plot: :: @@ -106,8 +108,8 @@ If you wish to re-enable interactive "live" modification of the plot: In recent versions of ``Matplotlib`` and ``IPython``, it is -sufficient to import `matplotlib.pyplot` and call `.pyplot.ion`. -Using the ``%`` magic is guaranteed to work in all versions of ``Matplotlib`` and ``IPython``. +sufficient to import `matplotlib.pyplot` and call `.pyplot.ion`. +Using the ``%`` magic is guaranteed to work in all versions of Matplotlib and IPython. .. highlight:: python @@ -139,43 +141,43 @@ Interactive mode controls: - whether created figures are automatically shown - whether changes to artists automatically trigger re-drawing existing figures -- when `.pyplot.show` exits: immediately, or after all of the figures have been closed if given no arguments +- when `.pyplot.show()` returns if given no arguments: immediately, or after all of the figures have been closed -Interactive mode: +If in interactive mode: - newly created figures will be displayed immediately - figures will automatically redraw when elements are changed -- `pyplot.show` displays the figures and immediately returns to the prompt - -Not in interactive mode: +- `pyplot.show()` displays the figures and immediately returns -- newly created figures and changes to figures are not displayed until -`.pyplot.show` is called again or `.pyplot.pause` exits -- `pyplot.show` runs the GUI event loop and does not return until all -the plot windows are closed +If not in interactive mode: +- newly created figures and changes to figures are not displayed until + * `.pyplot.show()` is called + * `.pyplot.pause()` is called + * `.FigureCanvasBase.flush_events()` is called +- `pyplot.show()` runs the GUI event loop and does not return until all the plot windows are closed If you are in non-interactive mode (or created figures while in non-interactive mode) you may need to explicitly call `.pyplot.show` to display the windows on your screen. If you only want to run the GUI event loop for a fixed amount of time, you can use `.pyplot.pause`. This will block the progress of your code as if you had called -`time.sleep`, ensure the current window is shown and re-drawn if needed, -and run the GUI event loop (so the windows are "live" for -interactive modification) for the specified period of time. - -The GUI event loop being integrated with your command prompt and -the figures being in interactive mode are independent of each other. -If you use `pyplot.ion` but have not arranged for the event loop integration, -your figures will appear but will not be "live" while the prompt is waiting for input. +`time.sleep`, ensure the current window is shown and re-drawn if needed, +and run the GUI event loop for the specified period of time. + +The GUI event loop being integrated with your command prompt and +the figures being in interactive mode are independent of each other. +If you use `pyplot.ion` but have not arranged for the event loop integration, +your figures will appear but will not be interactive while the prompt is waiting for input. You will not be able to pan/zoom and the figure may not even render (the window might appear black, transparent, or as a snapshot of the desktop under it). Conversely, if you configure the event loop -integration, displayed figures will be "live" while waiting for input -at the prompt, regardless of pyplot's "interactive mode". +integration, displayed figures will be responsive while waiting for input +at the prompt, regardless of pyplot's "interactive mode". -The figures will also be "live" if you use ``pyplot.show(block=True)``, -`.pyplot.pause`, or run the the GUI main loop in some other way. +No matter what combination of interactive mode setting and event loop integration, +figures will be responsive if you use ``pyplot.show(block=True)``, `.pyplot.pause`, or run +the GUI main loop in some other way. .. warning:: @@ -255,11 +257,11 @@ Jupyter Notebooks / Lab using an interactive backend. The default backend in notebooks, the inline backend, is not. `~ipykernel.pylab.backend_inline` renders the figure once and inserts a static image into the - notebook when the cell is executed. Because the images are static, they + notebook when the cell is executed. Because the images are static, they can not be panned / zoomed, take user input, or be updated from other cells. -To get interactive figures in the 'classic' notebook or Jupyter lab, +To get interactive figures in the 'classic' notebook or Jupyter lab, use the `ipympl `__ backend (must be installed separately) which uses the **ipywidget** framework. If ``ipympl`` is installed use the magic: @@ -276,17 +278,17 @@ If you only need to use the classic notebook, you can use %matplotlib notebook -which uses the `.backend_nbagg` backend which is installed by Matplotlib; +which uses the `.backend_nbagg` backend provided by Matplotlib; however, nbagg does not work in Jupyter Lab. GUIs + Jupyter ~~~~~~~~~~~~~~ -You can also use one of the non-ipympl GUI backends in a Jupyter Notebook. -If you are running your Jupyter kernel locally, the GUI window will spawn on -your desktop adjacent to your web browser. If you run your notebook on a remote server, -the kernel will try to open the GUI window on the remote computer. Unless you have -arranged to forward the xserver back to your desktop, you will not be able to +You can also use one of the non-``ipympl`` GUI backends in a Jupyter Notebook. +If you are running your Jupyter kernel locally, the GUI window will spawn on +your desktop adjacent to your web browser. If you run your notebook on a remote server, +the kernel will try to open the GUI window on the remote computer. Unless you have +arranged to forward the xserver back to your desktop, you will not be able to see or interact with the window. It may also raise an exception.