Skip to content

Commit

Permalink
Update Customizing Plots Docs with more description about .options (#…
Browse files Browse the repository at this point in the history 
…2923)
  • Loading branch information
@ahuang11 @philippjfr
ahuang11 authored and philippjfr committed Aug 13, 2018
1 parent 61a9cd6 commit 86e9202
Showing 1 changed file with 87 additions and 10 deletions.
97 changes: 87 additions & 10 deletions examples/user_guide/03-Customizing_Plots.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
"outputs": [],
"source": [
"spike_train = pd.read_csv('../assets/spike_train.csv.gz')\n",
"curve = hv.Curve( spike_train, 'milliseconds', 'Hertz')\n",
"curve = hv.Curve(spike_train, 'milliseconds', 'Hertz')\n",
"spikes = hv.Spikes(spike_train, 'milliseconds', [])"
]
},
Expand All @@ -63,13 +63,87 @@
"metadata": {},
"outputs": [],
"source": [
"%%output size=150\n",
"%%opts Curve [height=100 width=600 xaxis=None tools=['hover']]\n",
"%%opts Curve [height=100 width=600 xaxis=None tools=['hover']]\n",
"%%opts Curve (color='red' line_width=1.5)\n",
"%%opts Spikes [height=100 width=600 yaxis=None] (color='grey' line_width=0.25)\n",
"curve = hv.Curve( spike_train, 'milliseconds', vdims='Hertz')\n",
"curve = hv.Curve( spike_train, 'milliseconds', vdims='Hertz')\n",
"spikes = hv.Spikes(spike_train, 'milliseconds', vdims=[])\n",
"(curve + spikes).cols(1)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here it is, again, with the `.options` method, which is the simplest way of customizing because it will automatically deduce whether an option is a style, plot, or norm option. In addition, `.options` is portable across notebook environments and `.py` scripts."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"curve_opts = dict(height=100, width=600, xaxis=None, tools=[\n",
" 'hover'], color='red', line_width=1.5)\n",
"spike_opts = dict(height=100, width=600, yaxis=None,\n",
" color='grey', line_width=0.25)\n",
"\n",
"curve = hv.Curve(spike_train, 'milliseconds', 'Hertz')\n",
"spikes = hv.Spikes(spike_train, 'milliseconds', [])\n",
"\n",
"(curve.options(**curve_opts) + spikes.options(**spike_opts)).cols(1)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When using ``.options`` to apply options directly to an individual object we do not have to explicitly declare which object the options apply to, however often it is useful to set options on a composite object. In these cases the options can be declared as a dictionary of the type name and the options; it can also be accept a fully qualified `type.group.label` string. The code below is therefore equivalent to the syntax we used above:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"layout = (curve + spikes).options({'Curve': curve_opts, 'Spikes': spike_opts}).cols(1)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"There is, however, one advantage in using the `%%opts` magic when working in the notebook environment, and that is %%opts magic allows tab-completion of the options which is currently unavailable with the `.options` method.\n",
"f\n",
"Additionally, across the docs, you may encounter a legacy method `.opts`, which is now superseded by the `.options` method. \n",
"\n",
"`.opts` is essentially the Python script version of `%%opts`: in both, you'll have to manually categorize whether an option is a style, plot, or norm option.\n",
"\n",
"Ultimately, `.options` method is preferred because using `.opts` requires extreme verbosity in nested dictionaries, which can get overwhelming fast."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"curve = hv.Curve(spike_train, 'milliseconds', vdims='Hertz')\n",
"curve = curve.opts(\n",
" dict(plot={'Curve': dict(height=100, width=600,\n",
" xaxis=None, tools=['hover'])},\n",
" style={'Curve': dict(color='red', line_width=1.5)}\n",
" )\n",
")\n",
"spikes = hv.Spikes(spike_train, 'milliseconds', vdims=[])\n",
"(curve+spikes).cols(1)"
"spikes = spikes.opts(\n",
" dict(plot={'Spikes': dict(height=100, width=600, yaxis=None)},\n",
" style={'Spikes': dict(color='grey', line_width=0.25)})\n",
")\n",
"\n",
"(curve + spikes).cols(1)"
]
},
{
Expand Down Expand Up @@ -192,7 +266,7 @@
"\n",
"#### Dictionary format\n",
"\n",
"HoloViews avoids string parsing and special syntax (other than the basic operators described in [Composing Elements](./02-Composing_Elements.ipynb)) where possible. For this reason, all options are fundamentally reduced to a simple dictionary format. For example, here is the pure Python equivalent of the options shown above, using the ``opts`` method that will be described shortly:"
"HoloViews avoids string parsing and special syntax (other than the basic operators described in [Composing Elements](./02-Composing_Elements.ipynb)) where possible. For this reason, all options are fundamentally reduced to a simple dictionary format. For example, here is the pure Python equivalent of the options shown above, using the legacy ``opts`` method that will be described shortly:"
]
},
{
Expand Down Expand Up @@ -329,25 +403,28 @@
"\n",
"Here are the different ways of applying the options specifications and the accepted format:\n",
"\n",
"* *The ``%%opts`` cell magic*: IPython specific syntax applies to displayed object *[string format]*\n",
"* *The ``%%opts`` cell magic*: IPython specific syntax applies to displayed object *[string format]*\n",
"* *The ``%opts`` line magic*: IPython specific syntax applied globally *[string format]*\n",
"* *The ``.opts`` method*: Pure python method of HoloViews objects *[string format, dictionary format]*.\n",
"* *The ``.options`` method*: Higher level pure python method of HoloViews objects *[dictionary format]*.\n",
"* *The ``hv.opts`` utility*: Pure python equivalent to ``%opts`` and ``%%opts`` *[string format, dictionary format]*\n",
"\n",
"\n",
"In the notebook environment, the recommended approach is to use ``%opts`` for global settings at the top of the notebook, then ``%%opts`` to customize the output of specific cells and finally the ``.opts`` method as necessary. The ``hv.opts`` utility is mostly intended for use in Python scripts.\n",
"Across all environments, the recommended approach is to use ``.options``, and if you are unsure about the available options, you can apply `hv.help(obj)`, which will list all the available options for a given backend. If you are in a notebook environment, you may also utilize the tab completion ability from the ``%opts`` and ``%%opts`` magic.\n",
"\n",
"For the sake of completeness though: use ``%opts`` for global settings at the top of the notebook, then ``%%opts`` to customize the output of specific cells and finally the ``.opts`` method if you need backward compatibility of HoloViews. The ``hv.opts`` utility is mostly intended for use in Python scripts if you are used to the ``%opts`` syntax or copying from notebook.\n",
"\n",
"#### ``%%opts``\n",
"\n",
"As shown in the examples above, customizes a particular HoloViws output displayed in a code cell. This application is not global and persists for that object which means settings stay in place if the object is re-displayed. Only accepts the string specification format. All cell magics need to appear *above* any code in the cells they are used in and cannot be used if there is no code in the cell. Only accepts the string specification syntax.\n",
"As shown in the examples above, customizes a particular HoloViews output displayed in a code cell. This application is not global and persists for that object which means settings stay in place if the object is re-displayed. Only accepts the string specification format. All cell magics need to appear *above* any code in the cells they are used in and cannot be used if there is no code in the cell. Only accepts the string specification syntax.\n",
"\n",
"#### ``%opts``\n",
"\n",
"The ``%opts`` line magic is used to set global settings at the level of the notebook they are used in. If there are options you want to use throughout a notebook, they should be specified with ``%opts`` at the top of the notebook. Line magics can appear anywhere at the start of a line, whether in isolation or anywhere inside a cell containing code. Only accepts the string specification syntax.\n",
"\n",
"#### ``.opts`` method\n",
"\n",
"Used to specify options to a specific holoviews object. Useful to parameterize options programatically that can be hard to specify otherwise:"
"Used to specify options to a specific holoviews object. Legacy method."
]
},
{
Expand Down

0 comments on commit 86e9202

Please sign in to comment.