bokeh.models.sources¶
-
class
AjaxDataSource
(*args, **kw)[source]¶ Bases:
bokeh.models.sources.RemoteSource
A data source that can populate columns by making Ajax calls to REST endpoints.
The
AjaxDataSource
can be especially useful if you want to make a standalone document (i.e. not backed by the Bokeh server) that can still dynamically update using an existing REST API.The response from the REST API should match the
.data
property of a standardColumnDataSource
, i.e. a JSON dict that maps names to arrays of values:{ 'x' : [1, 2, 3, ...], 'y' : [9, 3, 2, ...] }
Alternatively, if the REST API returns a different format, a
CustomJS
callback can be provided to convert the REST response into Bokeh format, via theadapter
property of this data source.A full example can be seen at examples/howto/ajax_source.py
-
adapter
¶ property type:
Instance
(CustomJS
)A JavaScript callback to adapt raw JSON responses to Bokeh
ColumnDataSource
format.If provided, this callback is executes immediately after the JSON data is received, but before appending or replacing data in the data source. The
CustomJS
callback will receive theAjaxDataSource
ascb_obj
and will receive the raw JSON response ascb_data.response
. The callback code should return adata
object suitable for a BokehColumnDataSource
(i.e. a mapping of string column names to arrays of data).
-
http_headers
¶ property type:
Dict
(String
,String
)Specify HTTP headers to set for the Ajax request.
Example:
ajax_source.headers = { 'x-my-custom-header': 'some value' }
-
if_modified
¶ property type:
Bool
Whether to include an
If-Modified-Since
header in Ajax requests to the server. If this header is supported by the server, then only new data since the last request will be returned.
-
max_size
¶ property type:
Int
Maximum size of the data columns. If a new fetch would result in columns larger than
max_size
, then earlier data is dropped to make room.
-
-
class
CDSView
(**kwargs)[source]¶ Bases:
bokeh.model.Model
A view into a
ColumnDataSource
that represents a row-wise subset.-
source
¶ property type:
Instance
(ColumnarDataSource
)The
ColumnDataSource
associated with this view. Used to determine the length of the columns.
-
-
class
ColumnDataSource
(*args, **kw)[source]¶ Bases:
bokeh.models.sources.ColumnarDataSource
Maps names of columns to sequences or arrays.
The
ColumnDataSource
is a fundamental data structure of Bokeh. Most plots, data tables, etc. will be driven by aColumnDataSource
.If the
ColumnDataSource
initializer is called with a single argument that can be any of the following:A Python
dict
that maps string names to sequences of values, e.g. lists, arrays, etc.data = {'x': [1,2,3,4], 'y': np.ndarray([10.0, 20.0, 30.0, 40.0])} source = ColumnDataSource(data)
Note
ColumnDataSource
only creates a shallow copy ofdata
. Use e.g.ColumnDataSource(copy.deepcopy(data))
if initializing from anotherColumnDataSource.data
object that you want to keep independent.A Pandas
DataFrame
objectsource = ColumnDataSource(df)
In this case the CDS will have columns corresponding to the columns of the
DataFrame
. If theDataFrame
columns have multiple levels, they will be flattened using an underscore (e.g. level_0_col_level_1_col). The index of theDataFrame
will be flattened to anIndex
of tuples if it’s aMultiIndex
, and then reset usingreset_index
. The result will be a column with the same name if the index was named, or level_0_name_level_1_name if it was a namedMultiIndex
. If theIndex
did not have a name or theMultiIndex
name could not be flattened/determined, thereset_index
function will name the index columnindex
, orlevel_0
if the nameindex
is not available.A Pandas
GroupBy
objectgroup = df.groupby(('colA', 'ColB'))
In this case the CDS will have columns corresponding to the result of calling
group.describe()
. Thedescribe
method generates columns for statistical measures such asmean
andcount
for all the non-grouped original columns. The CDS columns are formed by joining original column names with the computed measure. For example, if aDataFrame
has columns'year'
and'mpg'
. Then passingdf.groupby('year')
to a CDS will result in columns such as'mpg_mean'
If the
GroupBy.describe
result has a named index column, then CDS will also have a column with this name. However, if the index name (or any subname of aMultiIndex
) isNone
, then the CDS will have a column generically namedindex
for the index.Note this capability to adapt
GroupBy
objects may only work with Pandas>=0.20.0
.
Note
There is an implicit assumption that all the columns in a given
ColumnDataSource
all have the same length at all times. For this reason, it is usually preferable to update the.data
property of a data source “all at once”.-
data
¶ property type:
ColumnData
(String
,Seq
(Any
) )Mapping of column names to sequences of data. The data can be, e.g, Python lists or tuples, NumPy arrays, etc.
-
__init__
(*args, **kw)[source]¶ If called with a single argument that is a dict or
pandas.DataFrame
, treat that implicitly as the “data” attribute.
-
add
(data, name=None)[source]¶ Appends a new column of data to the data source.
Parameters: - data (seq) – new data to add
- name (str, optional) – column name to use. If not supplied, generate a name of the form “Series ####”
Returns: the column name used
Return type:
-
classmethod
from_df
(data)[source]¶ Create a
dict
of columns from a PandasDataFrame
, suitable for creating aColumnDataSource
.Parameters: data (DataFrame) – data to convert Returns: dict[str, np.array]
-
classmethod
from_groupby
(data)[source]¶ Create a
dict
of columns from a PandasGroupBy
, suitable for creating aColumnDataSource
.The data generated is the result of running
describe
on the group.Parameters: data (Groupby) – data to convert Returns: dict[str, np.array]
-
patch
(patches, setter=None)[source]¶ Efficiently update data source columns at specific locations
If it is only necessary to update a small subset of data in a
ColumnDataSource
, this method can be used to efficiently update only the subset, instead of requiring the entire data set to be sent.This method should be passed a dictionary that maps column names to lists of tuples that describe a patch change to apply. To replace individual items in columns entirely, the tuples should be of the form:
(index, new_value) # replace a single column value # or (slice, new_values) # replace several column values
Values at an index or slice will be replaced with the corresponding new values.
In the case of columns whose values are other arrays or lists, (e.g. image or patches glyphs), it is also possible to patch “subregions”. In this case the first item of the tuple should be a whose first element is the index of the array item in the CDS patch, and whose subsequent elements are integer indices or slices into the array item:
# replace the entire 10th column of the 2nd array: +----------------- index of item in column data source | | +--------- row subindex into array item | | | | +- column subindex into array item V V V ([2, slice(None), 10], new_values)
Imagining a list of 2d NumPy arrays, the patch above is roughly equivalent to:
data = [arr1, arr2, ...] # list of 2d arrays data[2][:, 10] = new_data
There are some limitations to the kinds of slices and data that can be accepted.
- Negative
start
,stop
, orstep
values for slices will result in aValueError
. - In a slice,
start > stop
will result in aValueError
- When patching 1d or 2d subitems, the subitems must be NumPy arrays.
- New values must be supplied as a flattened one-dimensional array of the appropriate size.
Parameters: patches (dict[str, list[tuple]]) – lists of patches for each column Returns: None Raises: ValueError
Example:
The following example shows how to patch entire column elements. In this case,
source = ColumnDataSource(data=dict(foo=[10, 20, 30], bar=[100, 200, 300])) patches = { 'foo' : [ (slice(2), [11, 12]) ], 'bar' : [ (0, 101), (2, 301) ], } source.patch(patches)
After this operation, the value of the
source.data
will be:dict(foo=[11, 22, 30], bar=[101, 200, 301])
For a more comprehensive complete example, see examples/howto/patch_app.py.
- Negative
-
remove
(name)[source]¶ Remove a column of data.
Parameters: name (str) – name of the column to remove Returns: None Note
If the column name does not exist, a warning is issued.
-
stream
(new_data, rollover=None)[source]¶ Efficiently update data source columns with new append-only data.
In cases where it is necessary to update data columns in, this method can efficiently send only the new data, instead of requiring the entire data set to be re-sent.
Parameters: - new_data (dict[str, seq]) –
a mapping of column names to sequences of new data to append to each column.
All columns of the data source must be present in
new_data
, with identical-length append data. - rollover (int, optional) – A maximum column size, above which data from the start of the column begins to be discarded. If None, then columns will continue to grow unbounded (default: None)
Returns: None
Raises: Example:
source = ColumnDataSource(data=dict(foo=[], bar=[])) # has new, identical-length updates for all columns in source new_data = { 'foo' : [10, 20], 'bar' : [100, 200], } source.stream(new_data)
- new_data (dict[str, seq]) –
-
column_names
¶ A list of the column names in this data source.
-
class
ColumnarDataSource
(**kwargs)[source]¶ Bases:
bokeh.models.sources.DataSource
A base class for data source types, which can be mapped onto a columnar format.
Note
This is an abstract base class used to help organize the hierarchy of Bokeh model types. It is not useful to instantiate on its own.
-
selection_policy
¶ property type:
Instance
(SelectionPolicy
)An instance of a
SelectionPolicy
that determines how selections are set.
-
-
class
DataSource
(**kwargs)[source]¶ Bases:
bokeh.model.Model
A base class for data source types.
Note
This is an abstract base class used to help organize the hierarchy of Bokeh model types. It is not useful to instantiate on its own.
-
class
RemoteSource
(*args, **kw)[source]¶ Bases:
bokeh.models.sources.ColumnDataSource
Base class for remote column data sources that can update from data URLs at prescribed time intervals.
Note
This base class is typically not useful to instantiate on its own.
Note
This is an abstract base class used to help organize the hierarchy of Bokeh model types. It is not useful to instantiate on its own.