Anaconda Enterprise: Documentation

# 0.12.7

Bokeh Version `0.12.7` is an incremental update that adds a few important features and fixes several bugs. Some of the highlights include:

- Support graphs/trees/networks (#187) including configurable and extendable policies for highlighting and selection.
- Filterable/Sliceable CDS views (#4070)
- Pass HTTP request args to embedded sessions (#5992)
- New `Expression` models for client-side computations, including `Stack`, for stacking CDS columns.
- New module bokeh.transform with helper functions for simplifying `DataSpec` expressions, including `jitter()`, `dodge()`, `factor_cmap()`, etc.
- Added `hbar_stack()` and `vbar_stack()` to greatly simplify creation of stacked bar charts.
- Improvements for using Bokeh with Categorical data:
  - Support multi-level categories and hierarchical axes
  - Arbitrary limits on category names (e.g. no `':'`) have been lifted
  - Optional Pandas integration creates CDS from directly from `GroupBy` objects
  - Categorical Bar, Heatmap and Scatter plots easier to create with stable `bokeh.plotting` APIs
  - New User’s Guide chapter Handling Categorical Data

> Many other small bugfixes and docs additions. For full details see the CHANGELOG.

## Migration Guide

NOTE: the 0.12.x series is the last planned release series before a version 1.0 release. The focus of the 1.0 release will be implementing build automation to enforce API stability, and a very small number of high value features. For more information see the project roadmap.

### Breakage Related to Categoricals Overhaul

Bokeh support for Categorical data has needed attention for some time. The release brings improvements that dramatically improve the user experience when using categorical data with Bokeh. For details and examples, see the new User’s Guide chapter Handling Categorical Data.

At this point we endeavor to minimize breakage, and to provide managed deprecation cycles when things must change. However, in this instance, some minor immediate breaking changes were unavoidable:

- `min_interval` and `max_interval` on `FactorRange` are now given in synthetic coordinate units.
- `bounds` on `FactorRange` are now given in synthetic coordinate units.

### New Embed Functions for Bokeh Applications

Two new embed functions similar to `autoload_server` are added, that have simpler APIs and are more focused:

- `bokeh.embed.server_document()` for embedding new sessions for entire Bokeh documents in HTML pages. (More common)
- `bokeh.embed.server_session()` for embedding existing sessions for specified Bokeh models in HTML pages (Less common)

Additionally, with these new methods one may choose to not load the JS/CSS resource files by passing `resources="none"` as a parameter.

### Deprecations Removed

The following previously deprecated modules or features have been removed:

- `bokeh.icons` module
- Legacy anchor and legend locations `left_center` and `right_center`
- `ImageRGBA.rows` and `ImageRGBA.cols` properties
- `HBox` and `VBox` in `bokeh.layouts`
- `validate` keyword argument for `bokeh.io.save`

### New Deprecations

`bokeh.embed.autoload_server` has been deprecated and replaced with the two simpler functions `server_document()` and `server_session()` described above.

`bokeh.models.tools.tool_events` has been deprecated. Users should instead use the `SelectionGeometry` event present on `Plot` or `Figure`.

`DynamicImageRenderer` and `Plot.add_dyanamic_image` have been deprecated. For GIS-related use-cases built on top of Bokeh, consider using GeoViews, or creating a Custom Extension.

`ResizeTool` is deprecated and also immediately is a NO-OP on the Python side. `ResizeTool` has been removed from BokehJS entirely.

### BokehJS Widgets Bundle Split

The bokeh-widgets bundle was split into `bokeh-widgets` and `bokeh-tables`. This is to reduce the weight of the main widgets’ bundle. Bokeh includes `bokeh-tables` automatically when necessary, so this change should be transparent for most users. However, users of custom templates or other advanced embedding scenarios may be affected.

### TapTool Callback Calling Convention

The TapTool strayed from usual callback calling convention by passing a glyph data source as `cb_obj`. This has been rectified, and now the tool follows the usual convetion: the tool itself is passed as `cb_obj` and the data source is passed as part of the optional `cb_data`. Existing usage of `OpenURL` is unaffected by this change, but any `CustomJS` callbacks used with the tap tool will need to be updated to reflect this change.

### DataTable Selection Highlighting Signal

The DataTable now responds to the signal `source.change.emit()`, instead of `source.properties.selected.change.emit()`, to visually highlight the rows in the DataTable that are part of the selection. If you have used `source.properties.selected.change.emit()` in CustomJS code, you will need to change it to `source.change.emit()`.

The DataTable responds automatically to changes in its data source’s `selected` property. However, because of Bokeh’s change detection machinery, only a replacement of the `selected` property causes a change signal to be emitted, and not a partial update (e.g. `source.selected['1d']['indices'] = [1, 2]`). If you use a partial update in CustomJS code, you will need to emit the change signal yourself:

    customjs = CustomJS(args=dict(source=source), code="""
        source['selected']['1d'].indices = [1, 2]
        source.change.emit();
    """)

### Refactoring of `bokeh.server` contents

The `bokeh.server` module was refactored in order to be easier to document and maintain, as well as simpler for user’s to use in more sophisticated use cases. These changes are not expected to impact standard usage of Bokeh in any way:

- All protocol-related code was moved to a new module `bokeh.protocol`
- The `Server` class was split into `Server` (no API changes) and a new `BaseServer` that can be used when explicit coordination of low level Tornado components is required.
- Missing sections added to reference guide, and docsctring coverage greatly expanded.
- Old cruft code to handle Tornado < 4.3 (which is no longer supported) was removed.