Expanded and updated FAQ

doc/Comparisons.rst

@@ -1,17 +1,3 @@
-Comparing Panel and Voila
-=========================
-
-Panel and Voila both offer ways to deploy Python code as a standalone web server, built on very different server architectures (Bokeh Server for Panel, and Jupyter Server for Voila). Both servers are based on Tornado under the hood, but they differ in the fact that Jupyter will launch a new Python kernel for each user, while the Bokeh server can serve multiple users on the same process. This subtle difference has two major implications:
-
-1. The per-user overhead for a Bokeh app is much lower. Once the relevant libraries are imported, there is only a tiny bit of overhead for creating each new session. The Jupyter server, on the other hand, always launches an entirely new process, with all the overhead that entails. For a session that imports nothing but pandas and matplotlib the per-user overhead is 75 MB, which increases for more complex environments.
-
-2. Since a Bokeh server shares a single process for multiple sessions, data or processing can also be shared between the different sessions where appropriate. Such sharing makes it possible to further reduce the memory footprint of a Bokeh-Server app, to make it practical to support larger numbers of users and to provide faster startup or data-access times.
-
-The other major difference between Panel and Voila is the way they can be used in the notebook. Voila is built mainly around the notebook format. By default all output in the notebook is included in the rendered Voila app, which means existing notebooks can be served as apps unchanged, but then requires a complex custom template if you want to show only a subset of the outputs. Panel takes a different approach in that output needs to be explicitly wrapped in a Panel object and marked as being "servable", which makes it practical for the same notebook to serve both an exploratory purpose (in Jupyter) and act as a deployment (of a subset of the functionality). 
-
-From a user perspective the last major difference between the Panel and Voila is the types of output that can be included. Voila works with any output that can be rendered inside the Jupyter notebook, primarily focusing on ipywidgets-based interactive components. Panel currently renders a wide range of objects, but does not yet allow rendering ipywidgets. Upcoming Bokeh releases in 2019 are expected to add support for ipywidgets, so that the server choice can be made to optimize the other considerations above rather than being determined by the supported components.
-
-
 Comparing Panel and Bokeh
 =========================
 
@@ -31,14 +17,40 @@ Panel and Dash can both be used to create dashboards in Python, but take very di
 
 - Panel is plotting library agnostic, fully supporting a wide range of Python libraries out of the box, including Plotly. Dash has full support for Plotly, but other libraries have only limited support, using extension packages.
 
-- Dash dashboards work entirely on the client side (in the browser) once built, which has the advantage of being highly scalable for many simultaneous clients, but the disadvantage of not being able to perform server-side operations in Python like [Datashader](http://datashader.org).
+- Dash dashboards ordinarily keep all of their state at the client side (in the browser), which has the advantage of being highly scalable for many simultaneous clients, but the disadvantage of making it difficult to perform server-side operations in Python like [Datashader](http://datashader.org).
 
 
 Comparing Panel and ipywidgets
-=========================
+==============================
 
 Both Panel and ipywidgets (aka Jupyter Widgets) allow Python users to use widgets and create apps and dashboards from Python in Jupyter notebooks and in standalone servers (when paired with Voila). They are based on different, independently developed technologies for doing so, with some implications:
 
 - Panel is based on Bokeh widgets, which were developed separately from the Jupyter ecosystem, and designed from the start for standalone deployments.  Jupyter widgets, as the name suggests, were first developed specifically for the notebook environment, and only relatively recently (in 2019) adapted for standalone deployment. ipywidgets are still arguably better integrated into Jupyter, while Bokeh widgets have more solid support for server contexts.
 
 - ipywidgets expose more of the underlying HTML/CSS styling options, allowing them to be customized more heavily than Bokeh widgets currently allow.
+
+
+Comparing Panel and Voila
+=========================
+
+Voila is a technology for deploying Jupyter notebooks (with or without Panel code) as standalone web pages backed by Python. Voila is thus one way you can deploy your Panel apps, your ipywidgets-based apps, or any other content visible in a Jupyter notebook. Voila is an alternative to the Bokeh Server component that is available through ``panel serve``; Panel works with either one, and you can deploy with *either* Bokeh Server (panel serve) or Voila.  
+
+So, how do you choose between using Voila or Bokeh server?  First, at present (10/2019), Voila is the only way to deploy an app that contains both Bokeh-based components (including Panel objects) and ipywidgets-based components. So, if you want to deploy apps that contain ipyvolume, ipyleaflet, or bqplot components, you'll need Voila for serving, but you can also use any Panel object you wish, as long as you wrap it as an ipywidget using `jupyter_bokeh <https://github.com/bokeh/jupyter_bokeh>`__.  Just do `import jupyter_bokeh as jb ; jb.ipywidget(panel_obj)` and you can then mix Panel objects with ipywidgets in Voila.
+
+If you don't need ipywidgets, you can use either Bokeh Server or Voila for serving Panel objects. Which one should you choose?  Both servers are based on Tornado under the hood, but they differ in the fact that Jupyter will launch a new Python kernel for each user, while the Bokeh server can serve multiple users on the same process. This subtle difference has two major implications:
+
+1. The per-user overhead for a Bokeh app is much lower. Once the relevant libraries are imported, there is only a tiny bit of overhead for creating each new session. The Jupyter server, on the other hand, always launches an entirely new process, with all the overhead that entails. For a session that imports nothing but pandas and matplotlib the per-user overhead is 75 MB, which increases for more complex environments.
+
+2. Since a Bokeh server shares a single process for multiple sessions, data or processing can also be shared between the different sessions where appropriate. Such sharing makes it possible to further reduce the memory footprint of a Bokeh-Server app, to make it practical to support larger numbers of users and to provide faster startup or data-access times.
+
+The other major difference between Bokeh Server and Voila is the way they process notebook files. Voila is built directly on the notebook format. By default all output in the notebook is included in the rendered Voila app, which means existing notebooks can be served as apps _unchanged_. While that can be useful to get a quick set of plots, an existing notebook is unlikely to be organized and formatted in a way that forms a coherent dashboard, so in practice a notebook will need to be rewritten (some outputs suppressed, others rearranged) before it will make a good Voila dashboard, meaning that you end up with two copies of the notebook (one optimized to be a narrative, storytelling notebook with a series of cells, and another organized as a dashboard. Or you can write a template to select only the cells you want in the dashboard and rearrange them, but then you need to maintain both the notebook and the template separately.
+
+Panel takes a different approach in that output from a notebook cell needs to be explicitly wrapped in a Panel object and marked as being "servable"; cell outputs by default are shown only in the notebook, and not with ``panel serve``.  Panel in fact entirely ignores the fact that your notebook is organized into cells; it simply processes all the cells as Python code, and serves all the items that ended up being marked "servable".  Although this approach means editing the original notebook, it makes it practical for the same notebook to serve both an exploratory or storytelling purpose (in Jupyter) and act as a dashboard deployment (of a designated subset of the functionality). 
+
+
+Comparing Panel and streamlit
+=============================
+
+streamlit is an alternative to all of the above packages, including Jupyter, providing an interactive, incremental way to build apps (as in Jupyter), but by writing a Python file in a separate editor (as in Dash or Bokeh, and as opposed to using a cell-based Jupyter notebook). With streamlit, the entire source file is re-run every time a widget changes value, which has the advantage of not allowing confusing out-of-order execution of notebook cells. Using a Python source file allows users to choose their favorite editor rather than being limited to the web-based notebook interface, but it also typically means storing files locally rather than the client-server approach of notebooks that lets the source code live at a remote server while the user interface is local. In any case, for rerunning the entire file to be practical in any nontrivial case, streamlit requires all lengthy computations to be made cacheable, which is not always straightforward. A given Streamlit file produces a single application, as for Dash, though it can be incrementally built up in a simpler way than for Dash.
+
+Panel, in contrast to streamlit, fully supports Jupyter notebooks, for when you wish to preserve a series of text/code/output steps as an exploratory record, to document a workflow, or to tell a story about data.  Panel does not _require_ Jupyter, and in fact can be used just like streamlit, by launching `bokeh develop file.py`, which will watch the Python file for any changes and re-launch the served app each time; as for streamlit it would need caching mechanisms for such an approach to be viable in practice. Panel also supports fully reactive applications, where each widget or component of a plot is specifically tied to a bit of computation, re-running only the tiniest bit of code that is needed for that particular action. Panel can thus be used in a much wider range of applications than streamlit, including exploratory data analysis or capturing a reproducible workflow in a Jupyter notebook, developing a simple streamlit-like app, or developing complex, multi-page responsive apps, all without having to switch frameworks or learn a new set of tools. Panel thus supports the entire life cycle of data science, engineering, or scientific artifacts, not just a narrow task of developing a specific type of simple app.