Help on class GraphWidget in module plotly.widgets.graph_widget:
class GraphWidget(IPython.html.widgets.widget.DOMWidget)
| An interactive Plotly graph widget for use in IPython
| Notebooks.
|
| Method resolution order:
| GraphWidget
| IPython.html.widgets.widget.DOMWidget
| IPython.html.widgets.widget.Widget
| IPython.config.configurable.LoggingConfigurable
| IPython.config.configurable.Configurable
| IPython.utils.traitlets.HasTraits
| IPython.utils.traitlets._NewBase
| __builtin__.object
|
| Methods defined here:
|
| __init__(self, graph_url='https://plot.ly/~playground/7', **kwargs)
| Initialize a plotly graph widget
|
| Args:
| graph_url: The url of a Plotly graph
|
| Example:
| ```
| GraphWidget('https://plot.ly/~chris/3375')
| ```
|
| add_traces(self, traces, new_indices=None)
| Add new data traces to a graph.
|
| If `new_indices` isn't specified, they are simply appended.
|
| Args:
| traces (dict or list of dicts, or class of plotly.graph_objs):trace
| new_indices (list[int]|None), optional: The final indices the
| added traces should occupy in the graph.
|
| Examples:
| Initialization - Start each example below with this setup:
| ```
| from plotly.widgets import Graph
| from plotly.graph_objs import Scatter
| from IPython.display import display
|
| graph = GraphWidget('https://plot.ly/~chris/3979')
| display(graph)
| ```
|
| Example 1 - Add a scatter/line trace to the graph
| ```
| graph.add_traces(Scatter(x = [1, 2, 3], y = [5, 4, 5]))
| ```
|
| Example 2 - Add a scatter trace and set it to to be the
| second trace. This will appear as the second
| item in the legend.
| ```
| graph.add_traces(Scatter(x = [1, 2, 3], y = [5, 6, 5]),
| new_indices=[1])
| ```
|
| Example 3 - Add multiple traces to the graph
| ```
| graph.add_traces([
| Scatter(x = [1, 2, 3], y = [5, 6, 5]),
| Scatter(x = [1, 2.5, 3], y = [5, 8, 5])
| ])
| ```
|
| delete_traces(self, indices)
| Delete data traces from a graph.
|
| Args:
| indices (list[int]): The indices of the traces to be removed
|
| Example - Delete the 2nd trace:
| ```
| from plotly.widgets import Graph
| from IPython.display import display
|
| graph = GraphWidget('https://plot.ly/~chris/3979')
| display(graph)
|
|
| graph.delete_traces([1])
| ```
|
| hover(self, *hover_objs)
| Show hover labels over the points specified in hover_obj.
|
| Hover labels are the labels that normally appear when the
| mouse hovers over points in the plotly graph.
|
| Args:
| hover_objs (tuple of dicts):
| Specifies which points to place hover labels over.
|
| The location of the hover labels is described by a dict with
| keys and'xval' and/or 'yval' or 'curveNumber' and 'pointNumber'
| and optional keys 'hovermode' and 'subplot'
|
| 'xval' and 'yval' specify the (x, y) coordinates to
| place the label.
| 'xval' and 'yval need to be close to a point drawn in a graph.
|
| 'curveNumber' and 'pointNumber' specify the trace number and
| the index theof the point in that trace respectively.
|
| 'subplot' describes which axes to the coordinates refer to.
| By default, it is equal to 'xy'. For example, to specify the
| second x-axis and the third y-axis, set 'subplot' to 'x2y3'
|
| 'hovermode' is either 'closest', 'x', or 'y'.
| When set to 'x', all data sharing the same 'x' coordinate will
| be shown on screen with corresponding trace labels.
| When set to 'y' all data sharing the same 'y' coordinates will
| be shown on the screen with corresponding trace labels.
| When set to 'closest', information about the data point closest
| to where the viewer is hovering will appear.
|
| Note: If 'hovermode' is 'x', only 'xval' needs to be set.
| If 'hovermode' is 'y', only 'yval' needs to be set.
| If 'hovermode' is 'closest', 'xval' and 'yval' both
| need to be set.
|
| Note: 'hovermode' can be toggled by the user in the graph
| toolbar.
|
| Note: It is not currently possible to apply multiple hover
| labels to points on different axes.
|
| Note: `hover` can only be called with multiple dicts if
| 'curveNumber' and 'pointNumber' are the keys of the dicts
|
| Examples:
| Initialization - Start each example below with this setup:
| ```
| from plotly.widgets import Graph
| from IPython.display import display
|
| graph = GraphWidget('https://plot.ly/~chris/3979')
| display(graph)
| ```
|
| Example 1 - Apply a label to the (x, y) point (3, 2)
| ```
| graph.hover({'xval': 3, 'yval': 2, 'hovermode': 'closest'})
| ```
|
| Example 2 -Apply a labels to all the points with the x coordinate 3
| ```
| graph.hover({'xval': 3, 'hovermode': 'x'})
| ```
|
| Example 3 - Apply a label to the first point of the first trace
| and the second point of the second trace.
| ```
| graph.hover({'curveNumber': 0, 'pointNumber': 0},
| {'curveNumber': 1, 'pointNumber': 1})
| ```
|
| on_click(self, callback, remove=False)
| Assign a callback to click events propagated
| by clicking on point(s) in the Plotly graph.
|
| Args:
| callback (function): Callback function this is called
| on click events with the signature:
| callback(widget, hover_obj) -> None
|
| Args:
| widget (GraphWidget): The current instance
| of the graph widget that this callback is assigned to.
|
| click_obj (dict): a nested dict that describes
| which point(s) were clicked on.
|
| click_obj example:
| [
| {
| 'curveNumber': 1,
| 'pointNumber': 2,
| 'x': 4,
| 'y': 14
| }
| ]
|
| remove (bool, optional): If False, attach the callback.
| If True, remove the callback. Defaults to False.
|
|
| Returns:
| None
|
| Example:
| ```
| from IPython.display import display
| def message_handler(widget, msg):
| display(widget._graph_url)
| display(msg)
|
| g = GraphWidget('https://plot.ly/~chris/3375')
| display(g)
|
| g.on_click(message_handler)
| ```
|
| on_hover(self, callback, remove=False)
| Assign a callback to hover events propagated
| by hovering over points in the Plotly graph.
|
| Args:
| callback (function): Callback function this is called
| on hover events with the signature:
| callback(widget, hover_obj) -> None
|
| Args:
| widget (GraphWidget): The current instance
| of the graph widget that this callback is assigned to.
|
| hover_obj (dict): a nested dict that describes
| which point(s) was hovered over.
|
| hover_obj example:
| [
| {
| 'curveNumber': 1,
| 'pointNumber': 2,
| 'x': 4,
| 'y': 14
| }
| ]
|
| remove (bool, optional): If False, attach the callback.
| If True, remove the callback. Defaults to False.
|
|
| Returns:
| None
|
| Example:
| ```
| from IPython.display import display
| def message_handler(widget, hover_msg):
| display(widget._graph_url)
| display(hover_msg)
|
| g = GraphWidget('https://plot.ly/~chris/3375')
| display(g)
|
| g.on_hover(message_handler)
| ```
|
| on_zoom(self, callback, remove=False)
| Assign a callback to zoom events propagated
| by zooming in regions in the Plotly graph.
|
| Args:
| callback (function): Callback function this is called
| on zoom events with the signature:
| callback(widget, ranges) -> None
|
| Args:
| widget (GraphWidget): The current instance
| of the graph widget that this callback is assigned to.
|
| ranges (dict): A description of the
| region that was zoomed into.
|
| ranges example:
| {
| 'x': [1.8399058038561549, 2.16443359662],
| 'y': [4.640902872777017, 7.855677154582]
| }
|
| remove (bool, optional): If False, attach the callback.
| If True, remove the callback. Defaults to False.
|
| Returns:
| None
|
| Example:
| ```
| from IPython.display import display
| def message_handler(widget, ranges):
| display(widget._graph_url)
| display(ranges)
|
| g = GraphWidget('https://plot.ly/~chris/3375')
| display(g)
|
| g.on_zoom(message_handler)
| ```
|
| relayout(self, layout)
| Update the layout of the Plotly graph.
|
| Args:
| layout (dict):
| dict where keys are the graph attribute strings
| and values are the value of the graph attribute.
|
| To update graph objects that are nested, like
| the title of an axis, combine the keys with a period
| e.g. `xaxis.title`. To set a value of an element in an array,
| like an axis's range, use brackets, e.g. 'xaxis.range[0]'.
| To replace an entire nested object, just specify the value to
| the sub-object. See example 4 below.
|
| See all of the layout attributes in our reference documentation
| https://plot.ly/python/reference/#Layout
| Or by calling `help` on `plotly.graph_objs.Layout`
|
| Examples - Start each example below with this setup:
| Initialization:
| ```
| from plotly.widgets import Graph
| from IPython.display import display
|
| graph = GraphWidget('https://plot.ly/~chris/3979')
| display(graph)
| ```
|
| Example 1 - Update the title
| ```
| graph.relayout({'title': 'Experimental results'})
| ```
|
| Example 2 - Update the xaxis range
| ```
| graph.relayout({'xaxis.range': [-1, 6]})
| ```
|
| Example 3 - Update the first element of the xaxis range
| ```
| graph.relayout({'xaxis.range[0]': -3})
| ```
|
| Example 4 - Replace the entire xaxis object
| ```
| graph.relayout({'xaxis': {'title': 'Experimental results'}})
| ```
|
| reorder_traces(self, current_indices, new_indices=None)
| Reorder the traces in a graph.
|
| The order of the traces determines the order of the legend entries
| and the layering of the objects drawn in the graph, i.e. the first
| trace is drawn first and the second trace is drawn on top of the
| first trace.
|
| Args:
| current_indices (list[int]): The index of the traces to reorder.
|
| new_indices (list[int], optional): The index of the traces
| specified by `current_indices` after ordering.
| If None, then move the traces to the end.
|
| Examples:
| Example 1 - Move the first trace to the second to last
| position, the second trace to the last position
| ```
| graph.move_traces([0, 1])
| ```
|
| Example 2 - Move the first trace to the second position,
| the second trace to the first position.
| ```
| graph.move_traces([0], [1])
| ```
|
| restyle(self, data, indices=None)
| Update the style of existing traces in the Plotly graph.
|
| Args:
| update (dict):
| dict where keys are the graph attribute strings
| and values are the value of the graph attribute.
|
| To update graph objects that are nested, like
| a marker's color, combine the keys with a period,
| e.g. `marker.color`. To replace an entire nested object,
| like `marker`, set the value to the object.
| See Example 2 below.
|
| To update an attribute of multiple traces, set the
| value to an list of values. If the list is shorter
| than the number of traces, the values will wrap around.
| Note: this means that for values that are naturally an array,
| like `x` or `colorscale`, you need to wrap the value
| in an extra array,
| i.e. {'colorscale': [[[0, 'red'], [1, 'green']]]}
|
| You can also supply values to different traces with the
| indices argument.
|
| See all of the graph attributes in our reference documentation
| here: https://plot.ly/python/reference or by calling `help` on
| graph objects in `plotly.graph_objs`.
|
| indices (list, optional):
| Specify which traces to apply the update dict to.
| Negative indices are supported.
| If indices are not given, the update will apply to
| *all* traces.
|
| Examples:
| Initialization - Start each example below with this setup:
| ```
| from plotly.widgets import Graph
| from IPython.display import display
|
| graph = GraphWidget('https://plot.ly/~chris/3979')
| display(graph)
| ```
|
| Example 1 - Set `marker.color` to red in every trace in the graph
| ```
| graph.restyle({'marker.color': 'red'})
| ```
|
| Example 2 - Replace `marker` with {'color': 'red'}
| ```
| graph.restyle({'marker': {'color': red'}})
| ```
|
| Example 3 - Set `marker.color` to red
| in the first trace of the graph
| ```
| graph.restyle({'marker.color': 'red'}, indices=[0])
| ```
|
| Example 4 - Set `marker.color` of all of the traces to
| alternating sequences of red and green
| ```
| graph.restyle({'marker.color': ['red', 'green']})
| ```
|
| Example 5 - Set just `marker.color` of the first two traces
| to red and green
| ```
| graph.restyle({'marker.color': ['red', 'green']}, indices=[0, 1])
| ```
|
| Example 6 - Set multiple attributes of all of the traces
| ```
| graph.restyle({
| 'marker.color': 'red',
| 'line.color': 'green'
| })
| ```
|
| Example 7 - Update the data of the first trace
| ```
| graph.restyle({
| 'x': [[1, 2, 3]],
| 'y': [[10, 20, 30]],
| }, indices=[0])
| ```
|
| Example 8 - Update the data of the first two traces
| ```
| graph.restyle({
| 'x': [[1, 2, 3],
| [1, 2, 4]],
| 'y': [[10, 20, 30],
| [5, 8, 14]],
| }, indices=[0, 1])
| ```
|
| ----------------------------------------------------------------------
| Methods inherited from IPython.html.widgets.widget.DOMWidget:
|
| add_class(self, class_names, selector='')
| Add class[es] to a DOM element.
|
| Parameters
| ----------
| class_names: unicode or list
| Class name(s) to add to the DOM element(s).
| selector: unicode (optional)
| JQuery selector to select the DOM element(s) that the class(es) will
| be added to.
|
| get_css(self, key, selector='')
| Get a CSS property of the widget.
|
| Note: This function does not actually request the CSS from the
| front-end; Only properties that have been set with set_css can be read.
|
| Parameters
| ----------
| key: unicode
| CSS key
| selector: unicode (optional)
| JQuery selector used when the CSS key/value was set.
|
| remove_class(self, class_names, selector='')
| Remove class[es] from a DOM element.
|
| Parameters
| ----------
| class_names: unicode or list
| Class name(s) to remove from the DOM element(s).
| selector: unicode (optional)
| JQuery selector to select the DOM element(s) that the class(es) will
| be removed from.
|
| set_css(self, dict_or_key, value=None, selector='')
| Set one or more CSS properties of the widget.
|
| This function has two signatures:
| - set_css(css_dict, selector='')
| - set_css(key, value, selector='')
|
| Parameters
| ----------
| css_dict : dict
| CSS key/value pairs to apply
| key: unicode
| CSS key
| value:
| CSS value
| selector: unicode (optional, kwarg only)
| JQuery selector to use to apply the CSS key/value. If no selector
| is provided, an empty selector is used. An empty selector makes the
| front-end try to apply the css to a default element. The default
| element is an attribute unique to each view, which is a DOM element
| of the view that should be styled with common CSS (see
| `$el_to_style` in the Javascript code).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IPython.html.widgets.widget.DOMWidget:
|
| visible
| A boolean (True, False) trait.
|
| ----------------------------------------------------------------------
| Methods inherited from IPython.html.widgets.widget.Widget:
|
| __del__(self)
| Object disposal
|
| close(self)
| Close method.
|
| Closes the widget which closes the underlying comm.
| When the comm is closed, all of the widget views are automatically
| removed from the front-end.
|
| get_state(self, key=None)
| Gets the widget state, or a piece of it.
|
| Parameters
| ----------
| key : unicode (optional)
| A single property's name to get.
|
| on_displayed(self, callback, remove=False)
| (Un)Register a widget displayed callback.
|
| Parameters
| ----------
| callback: method handler
| Must have a signature of::
|
| callback(widget, **kwargs)
|
| kwargs from display are passed through without modification.
| remove: bool
| True if the callback should be unregistered.
|
| on_msg(self, callback, remove=False)
| (Un)Register a custom msg receive callback.
|
| Parameters
| ----------
| callback: callable
| callback will be passed two arguments when a message arrives::
|
| callback(widget, content)
|
| remove: bool
| True if the callback should be unregistered.
|
| send(self, content)
| Sends a custom msg to the widget model in the front-end.
|
| Parameters
| ----------
| content : dict
| Content of the message to send.
|
| send_state(self, key=None)
| Sends the widget state, or a piece of it, to the front-end.
|
| Parameters
| ----------
| key : unicode (optional)
| A single property's name to sync with the front-end.
|
| ----------------------------------------------------------------------
| Static methods inherited from IPython.html.widgets.widget.Widget:
|
| on_widget_constructed(callback)
| Registers a callback to be called when a widget is constructed.
|
| The callback must have the following signature:
| callback(widget)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IPython.html.widgets.widget.Widget:
|
| comm
| Gets the Comm associated with this widget.
|
| If a Comm doesn't exist yet, a Comm will be created automagically.
|
| keys
| An instance of a Python list.
|
| model_id
| Gets the model id of this widget.
|
| If a Comm doesn't exist yet, a Comm will be created automagically.
|
| msg_throttle
| An int trait.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from IPython.html.widgets.widget.Widget:
|
| widgets = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IPython.config.configurable.LoggingConfigurable:
|
| log
| A trait whose value must be an instance of a specified class.
|
| The value can also be an instance of a subclass of the specified class.
|
| ----------------------------------------------------------------------
| Methods inherited from IPython.config.configurable.Configurable:
|
| update_config(self, config)
| Fire the traits events when the config is updated.
|
| ----------------------------------------------------------------------
| Class methods inherited from IPython.config.configurable.Configurable:
|
| class_config_section(cls) from IPython.utils.traitlets.MetaHasTraits
| Get the config class config section
|
| class_get_help(cls, inst=None) from IPython.utils.traitlets.MetaHasTraits
| Get the help string for this class in ReST format.
|
| If `inst` is given, it's current trait values will be used in place of
| class defaults.
|
| class_get_trait_help(cls, trait, inst=None) from IPython.utils.traitlets.MetaHasTraits
| Get the help string for a single trait.
|
| If `inst` is given, it's current trait values will be used in place of
| the class default.
|
| class_print_help(cls, inst=None) from IPython.utils.traitlets.MetaHasTraits
| Get the help string for a single trait and print it.
|
| section_names(cls) from IPython.utils.traitlets.MetaHasTraits
| return section names as a list
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IPython.config.configurable.Configurable:
|
| config
| A trait whose value must be an instance of a specified class.
|
| The value can also be an instance of a subclass of the specified class.
|
| parent
| A trait whose value must be an instance of a specified class.
|
| The value can also be an instance of a subclass of the specified class.
|
| ----------------------------------------------------------------------
| Methods inherited from IPython.utils.traitlets.HasTraits:
|
| on_trait_change(self, handler, name=None, remove=False)
| Setup a handler to be called when a trait changes.
|
| This is used to setup dynamic notifications of trait changes.
|
| Static handlers can be created by creating methods on a HasTraits
| subclass with the naming convention '_[traitname]_changed'. Thus,
| to create static handler for the trait 'a', create the method
| _a_changed(self, name, old, new) (fewer arguments can be used, see
| below).
|
| Parameters
| ----------
| handler : callable
| A callable that is called when a trait changes. Its
| signature can be handler(), handler(name), handler(name, new)
| or handler(name, old, new).
| name : list, str, None
| If None, the handler will apply to all traits. If a list
| of str, handler will apply to all names in the list. If a
| str, the handler will apply just to that name.
| remove : bool
| If False (the default), then install the handler. If True
| then unintall it.
|
| trait_metadata(self, traitname, key)
| Get metadata values for trait by key.
|
| trait_names(self, **metadata)
| Get a list of all the names of this class' traits.
|
| traits(self, **metadata)
| Get a `dict` of all the traits of this class. The dictionary
| is keyed on the name and the values are the TraitType objects.
|
| The TraitTypes returned don't know anything about the values
| that the various HasTrait's instances are holding.
|
| The metadata kwargs allow functions to be passed in which
| filter traits based on metadata values. The functions should
| take a single value as an argument and return a boolean. If
| any function returns False, then the trait is not included in
| the output. This does not allow for any simple way of
| testing that a metadata name exists and has any
| value because get_metadata returns None if a metadata key
| doesn't exist.
|
| ----------------------------------------------------------------------
| Class methods inherited from IPython.utils.traitlets.HasTraits:
|
| class_trait_names(cls, **metadata) from IPython.utils.traitlets.MetaHasTraits
| Get a list of all the names of this class' traits.
|
| This method is just like the :meth:`trait_names` method,
| but is unbound.
|
| class_traits(cls, **metadata) from IPython.utils.traitlets.MetaHasTraits
| Get a `dict` of all the traits of this class. The dictionary
| is keyed on the name and the values are the TraitType objects.
|
| This method is just like the :meth:`traits` method, but is unbound.
|
| The TraitTypes returned don't know anything about the values
| that the various HasTrait's instances are holding.
|
| The metadata kwargs allow functions to be passed in which
| filter traits based on metadata values. The functions should
| take a single value as an argument and return a boolean. If
| any function returns False, then the trait is not included in
| the output. This does not allow for any simple way of
| testing that a metadata name exists and has any
| value because get_metadata returns None if a metadata key
| doesn't exist.
|
| ----------------------------------------------------------------------
| Static methods inherited from IPython.utils.traitlets.HasTraits:
|
| __new__(cls, *args, **kw)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IPython.utils.traitlets._NewBase:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)