def notebook_interaction(self, display=True):
from ipywidgets import Checkbox
from traitlets import TraitError as TraitletError
from IPython.display import display as ip_display
try:
container = super(ScalableFixedPattern,
self).notebook_interaction(display=False)
interpolate = Checkbox(description='interpolate',
value=self.interpolate)
def on_interpolate_change(change):
self.interpolate = change['new']
interpolate.observe(on_interpolate_change, names='value')
container.children = (container.children[0], interpolate) + \
container.children[1:]
if not display:
return container
ip_display(container)
except TraitletError:
if display:
print('This function is only avialable when running in a'
' notebook')
else:
raise
def display_video_file(fname, width=None, height=None):
"""
Display a video file
:param fname: filename
:param width: desired width of the video (optional)
:param height: desired height of the video (optional)
"""
assert in_ipython_context, "Display only works in an IPython notebook"
if isinstance(width, int):
width_str = "width={}".format(width)
else:
width_str=""
if isinstance(height, int):
height_str = "height={}".format(height)
else:
height_str=""
html_source = """
<video {} {} controls loop="loop">
<source src="{}" type="video/mp4">
</video>
""".format(width_str, height_str, fname)
# noinspection PyTypeChecker
ip_display(HTML(html_source))
def notebook_interaction(self, display=True):
"""Creates interactive notebook widgets for all component parameters,
if available.
Requires `ipywidgets` to be installed.
Parameters
----------
display : bool
if True (default), attempts to display the widgets.
Otherwise returns the formatted widget object.
"""
from ipywidgets import (Checkbox, VBox)
from traitlets import TraitError as TraitletError
from IPython.display import display as ip_display
try:
active = Checkbox(description='active', value=self.active)
def on_active_change(change):
self.active = change['new']
active.observe(on_active_change, names='value')
container = VBox([active])
for parameter in self.parameters:
container.children += parameter.notebook_interaction(False),
if not display:
return container
ip_display(container)
except TraitletError:
if display:
_logger.info('This function is only avialable when running in'
' a notebook')
else:
raise
def record(name, value):
"""
Record a value in the output notebook when a cell is executed.
The recorded value can be retrieved during later inspection of the
output notebook.
Example
-------
`record` provides a handy way for data to be stored with a notebook to
be used later::
pm.record("hello", "world")
pm.record("number", 123)
pm.record("some_list", [1, 3, 5])
pm.record("some_dict", {"a": 1, "b": 2})
pandas can be used later to recover recorded values by
reading the output notebook into a `dataframe`::
nb = pm.read_notebook('notebook.ipynb')
nb.dataframe
Parameters
----------
name : str
Name of the value to record.
value: str, int, float, list, dict
The value to record.
"""
# IPython.display.display takes a tuple of objects as first parameter
# `http://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display`
data = {RECORD_OUTPUT_TYPE: {name: value}}
ip_display(data, raw=True)
def notebook_interaction(self, display=True):
"""Creates interactive notebook widgets for the parameter, if
available.
Requires `ipywidgets` to be installed.
Parameters
----------
display : bool
if True (default), attempts to display the parameter widget.
Otherwise returns the formatted widget object.
"""
from ipywidgets import VBox
from traitlets import TraitError as TraitletError
from IPython.display import display as ip_display
try:
if self._number_of_elements == 1:
container = self._create_notebook_widget()
else:
children = [self._create_notebook_widget(index=i) for i in
range(self._number_of_elements)]
container = VBox(children)
if not display:
return container
ip_display(container)
except TraitletError:
if display:
_logger.info('This function is only avialable when running in'
' a notebook')
else:
raise
def notebook_interaction(self, display=True):
from ipywidgets import Checkbox
from traitlets import TraitError as TraitletError
from IPython.display import display as ip_display
try:
container = super(ScalableFixedPattern,
self).notebook_interaction(display=False)
interpolate = Checkbox(description='interpolate',
value=self.interpolate)
def on_interpolate_change(change):
self.interpolate = change['new']
interpolate.observe(on_interpolate_change, names='value')
container.children = (container.children[0], interpolate) + \
container.children[1:]
if not display:
return container
ip_display(container)
except TraitletError:
if display:
print('This function is only avialable when running in a'
' notebook')
else:
raise
def notebook_interaction(self, display=True):
"""Creates interactive notebook widgets for all component parameters,
if available.
Requires `ipywidgets` to be installed.
Parameters
----------
display : bool
if True (default), attempts to display the widgets.
Otherwise returns the formatted widget object.
"""
from ipywidgets import (Checkbox, VBox)
from traitlets import TraitError as TraitletError
from IPython.display import display as ip_display
try:
active = Checkbox(description='active', value=self.active)
def on_active_change(change):
self.active = change['new']
active.observe(on_active_change, names='value')
container = VBox([active])
for parameter in self.parameters:
container.children += parameter.notebook_interaction(False),
if not display:
return container
ip_display(container)
except TraitletError:
if display:
_logger.info('This function is only avialable when running in'
' a notebook')
else:
raise
def sketch(name, obj):
"""
Display a named snap (visible display output) in a retrievable manner.
Unlike `glue` this is intended to generate a snap for notebook interfaces to render.
Example
-------
sb.sketch("hello", "Hello World")
sb.sketch("sharable_png", IPython.display.Image(filename=get_fixture_path("sharable.png")))
Like scraps these can be retrieved at a later time, though they don't cary
any actual data, just the display result of some object.
nb = sb.read_notebook('notebook.ipynb')
nb.snaps
More usefully, you can copy snaps from earlier executions to re-display the
object in the current notebook.
nb = sb.read_notebook('notebook.ipynb')
nb.resketch("sharable_png")
Parameters
----------
name : str
Name of the output.
obj : object
An object that can be displayed in the notebook.
"""
data, metadata = IPython.core.formatters.format_display_data(obj)
metadata["scrapbook"] = dict(name=name)
ip_display(data, metadata=metadata, raw=True)
def notebook_interaction(self, display=True):
"""Creates interactive notebook widgets for the parameter, if
available.
Requires `ipywidgets` to be installed.
Parameters
----------
display : bool
if True (default), attempts to display the parameter widget.
Otherwise returns the formatted widget object.
"""
from ipywidgets import VBox
from traitlets import TraitError as TraitletError
from IPython.display import display as ip_display
try:
if self._number_of_elements == 1:
container = self._create_notebook_widget()
else:
children = [
self._create_notebook_widget(index=i)
for i in range(self._number_of_elements)
]
container = VBox(children)
if not display:
return container
ip_display(container)
except TraitletError:
if display:
_logger.info('This function is only avialable when running in'
' a notebook')
else:
raise
def display_output(self, name):
"""Display the output from this notebook in the running notebook."""
outputs = _get_notebook_outputs(self.node)
if name not in outputs:
raise PapermillException(
"Output Name '%s' is not available in this notebook.")
output = outputs[name]
ip_display(output.data, metadata=output.metadata, raw=True)
def display_frame(self, frame_number=None):
"""
Display the plot of a single frame.
:param frame_number: optional, index of frame to plot, defaults to the last frame
:return:
"""
assert in_ipython_context, "Display only works in an IPython notebook"
fig = self.plot_frame(frame_number)
ip_display(fig)
def record(name, value):
"""
Records the value as part of the executing cell's output to be retrieved during inspection.
Args:
name (str): Name of the value
value: The value to record.
"""
ip_display({RECORD_OUTPUT_TYPE: {name: value}}, raw=True)
def display(name, obj):
"""
Displays an object with the reference 'name'.
Args:
name (str): Name of the output.
obj: An object that can be displayed in the notebook.
"""
data, metadata = IPython.core.formatters.format_display_data(obj)
metadata['papermill'] = dict(name=name)
ip_display(data, metadata=metadata, raw=True)
def record(name, value):
"""
Records the value as part of the executing cell's output to be retrieved
during inspection.
Args:
name (str): Name of the value
value: The value to record.
"""
# IPython.display.display takes a tuple of objects as first parameter
# `http://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display`
ip_display(({RECORD_OUTPUT_TYPE: {name: value}}, ), raw=True)
def display_output(self, name):
"""Display output from a named source notebook in a running notebook.
Parameters
----------
name : str
name of source notebook
"""
outputs = _get_notebook_outputs(self.node)
if name not in outputs:
raise PapermillException("Output Name '%s' is not available in this notebook." % name)
output = outputs[name]
ip_display(output.data, metadata=output.metadata, raw=True)
def show_video():
mp4list = glob.glob('video/*.mp4')
if len(mp4list) > 0:
mp4 = mp4list[0]
video = io.open(mp4, 'r+b').read()
encoded = base64.b64encode(video)
ip_display(
HTML(data='''
<video alt="test" autoplay
loop controls style="height: 400px;">
<source src="data:video/mp4;base64,{0}" type="video/mp4" />
</video>'''.format(encoded.decode('ascii'))))
else:
print("Could not find video")
def notebook_interaction(self, display=True):
from ipywidgets import (Checkbox, FloatSlider, VBox)
from traitlets import TraitError as TraitletError
from IPython.display import display as ip_display
try:
active = Checkbox(description='active', value=self.active)
def on_active_change(change):
self.active = change['new']
active.observe(on_active_change, names='value')
fine_structure = Checkbox(description='Fine structure',
value=self.fine_structure_active)
def on_fine_structure_active_change(change):
self.fine_structure_active = change['new']
fine_structure.observe(on_fine_structure_active_change,
names='value')
fs_smoothing = FloatSlider(description='Fine structure smoothing',
min=0,
max=1,
step=0.001,
value=self.fine_structure_smoothing)
def on_fs_smoothing_change(change):
self.fine_structure_smoothing = change['new']
fs_smoothing.observe(on_fs_smoothing_change, names='value')
container = VBox([active, fine_structure, fs_smoothing])
for parameter in [
self.intensity, self.effective_angle, self.onset_energy
]:
container.children += parameter.notebook_interaction(False),
if not display:
return container
ip_display(container)
except TraitletError:
if display:
print('This function is only avialable when running in a'
' notebook')
else:
raise
def display(name, obj):
"""
Display an object with the reference `name`.
Parameters
----------
name : str
Name of the output.
obj : object
An object that can be displayed in the notebook.
"""
data, metadata = IPython.core.formatters.format_display_data(obj)
metadata['papermill'] = dict(name=name)
ip_display(data, metadata=metadata, raw=True)
def display(self, with_js=True):
"""
Display the animation.
:param with_js: should the displayed element have fancy playback controls
See also: display_video_file (function)
"""
assert in_ipython_context, "Display only works in an IPython notebook"
if with_js:
html_source = self.to_animation().to_jshtml()
else:
html_source = self.to_animation().to_html5_video()
# noinspection PyTypeChecker
ip_display(HTML(html_source))
def notebook_interaction(self, display=True):
from ipywidgets import (Checkbox, FloatSlider, VBox)
from traitlets import TraitError as TraitletError
from IPython.display import display as ip_display
try:
active = Checkbox(description='active', value=self.active)
def on_active_change(change):
self.active = change['new']
active.observe(on_active_change, names='value')
fine_structure = Checkbox(description='Fine structure',
value=self.fine_structure_active)
def on_fine_structure_active_change(change):
self.fine_structure_active = change['new']
fine_structure.observe(on_fine_structure_active_change,
names='value')
fs_smoothing = FloatSlider(description='Fine structure smoothing',
min=0, max=1, step=0.001,
value=self.fine_structure_smoothing)
def on_fs_smoothing_change(change):
self.fine_structure_smoothing = change['new']
fs_smoothing.observe(on_fs_smoothing_change, names='value')
container = VBox([active, fine_structure, fs_smoothing])
for parameter in [self.intensity, self.effective_angle,
self.onset_energy]:
container.children += parameter.notebook_interaction(False),
if not display:
return container
ip_display(container)
except TraitletError:
if display:
print('This function is only avialable when running in a'
' notebook')
else:
raise
def plot(self, variables_values, axes=None):
"""
Plot for some specific variable values.
:param variables_values: iterable of values for all free variables
:param axes: the matplotlib axes to plot on, one will be created if none is given
"""
assert len(self.variables) == len(variables_values), \
f"You need to pass as many variable values as this visualiser has variables. Required:" \
f"{len(self.variables)}, Given: {len(variables_values)}"
fig = None
if axes is None:
fig, axes = self.create_default_axes()
# TODO: Probably should not do that, but it prevents an empty plot from popping up in IPython
plt.close(fig)
self.plot_init(variables_values, axes)
self.plot_update(variables_values, axes)
if fig is not None and in_ipython_context:
ip_display(fig)
def resketch(self, name, raise_error=True):
"""
Display output from a named source of the notebook.
Parameters
----------
name : str
name of sketched (snap) object
raise_error : bool
indicator for if the resketch should print a message or error on missing snaps
"""
if name not in self.snaps:
if raise_error:
raise ScrapbookException(
"Frame '{}' is not available in this notebook.".format(
name))
else:
ip_display("No snap available for {}".format(name))
else:
output = self.snaps[name]
ip_display(output.data, metadata=output.metadata, raw=True)
def plot_onion_skinned(self, variables_values, axes=None, max_lightness=0.9):
"""
!!! EXPERIMENTAL !!!
Plot multiple configurations in one picture with 'older' data shown lighter
:param variables_values: 2D NumPy array, each row as one set of variable values
:param axes: the matplotlib axes to plot on, one will be created if none is given
"""
assert len(self.variables) == variables_values.shape[1], \
f"You need to pass as many variable values as this visualiser has variables. Required:" \
f"{len(self.variables)}, Given: {variables_values.shape[1]}"
fig = None
if axes is None:
fig, axes = self.create_default_axes()
# TODO: Probably should not do that, but it prevents an empty plot from popping up in IPython
plt.close(fig)
total_frames = variables_values.shape[0]
for i in range(total_frames):
frame_values = variables_values[i]
i_norm = i / (total_frames - 1) # 0.0 is iteration start, 1.0 is last iteration
drawables = self.plot_init(frame_values, axes)
for drawable in drawables:
orig_mpl_color = drawable.get_color()
orig_rgb = colors.to_rgb(orig_mpl_color) # 3-tuple of floats [0, 1]
# convert to hue, lightness, saturation color space
orig_h, orig_l, orig_s = colorsys.rgb_to_hls(*orig_rgb)
# interpolate, max_lightness for oldest frame, original lightness for newest
#new_l = orig_l + (max_lightness - orig_l) * (1 - i_norm) # linear interpolation
new_l = (orig_l - max_lightness) * i_norm**2 + max_lightness # quadratic, local max at higher brightness
new_rgb = colorsys.hls_to_rgb(orig_h, new_l, orig_s)
drawable.set_color(new_rgb)
if fig is not None and in_ipython_context:
ip_display(fig)
def reglue(self,
name,
new_name=None,
raise_on_missing=True,
unattached=False):
"""
Display output from a named source of the notebook.
Parameters
----------
name : str
name of scrap object
new_name : str
replacement name for scrap
raise_error : bool
indicator for if the resketch should print a message or error on missing snaps
unattached : bool
indicator for rendering without making the display recallable as scrapbook data
"""
# Avoid circular imports and make slow imports lazy
from .api import _prepare_ipy_data_format, _prepare_ipy_display_format
from IPython.display import display as ip_display
if name not in self.scraps:
if raise_on_missing:
raise ScrapbookException(
"Scrap '{}' is not available in this notebook.".format(
name))
else:
ip_display(
"No scrap found with name '{}' in this notebook".format(
name))
else:
scrap = self.scraps[name]
if new_name:
scrap = scrap._replace(name=new_name)
if scrap.data is not None:
data, metadata = _prepare_ipy_data_format(
scrap.name, scrap_to_payload(scrap), scrap.encoder)
# Skip saving data for later regluing and remove 'scrapbook'
# from keys, when unattached
if unattached:
metadata = self._strip_scrapbook_metadata(metadata)
ip_display(data, metadata=metadata, raw=True)
if scrap.display is not None:
scrap_data = scrap.display.get("data", {})
scrap_metadata = self._strip_scrapbook_metadata(
scrap.display.get("metadata", {}))
data, metadata = _prepare_ipy_display_format(
scrap.name, scrap_data, scrap_metadata)
if unattached:
# Remove 'scrapbook' from keys if we want it unassociated
metadata = self._strip_scrapbook_metadata(metadata)
ip_display(data, metadata=metadata, raw=True)
def display_output(self, key, output_name):
if isinstance(key, string_types):
ip_display(Markdown("### %s" % str(key)))
self[key].display_output(output_name)
else:
for i, k in enumerate(key):
if i > 0:
# between outputs
ip_display(Markdown("<hr>"))
ip_display(Markdown("### %s" % str(k)))
self[k].display_output(output_name)
def display_output(self, key, output_name):
"""Display markdown of output"""
if isinstance(key, string_types):
ip_display((Markdown("### %s" % str(key)), ))
self[key].display_output(output_name)
else:
for i, k in enumerate(key):
if i > 0:
ip_display((Markdown("<hr>"), )) # tag between outputs
ip_display((Markdown("### %s" % str(k)), ))
self[k].display_output(output_name)
def display_output(self, key, output_name):
"""Display output as markdown.
Parameters
----------
key : str
parameter names to be used as markdown headings in output
output_name : str
a named notebook to display as output
"""
if isinstance(key, string_types):
ip_display(Markdown("### %s" % str(key)))
self[key].display_output(output_name)
else:
for i, k in enumerate(key):
if i > 0:
ip_display(Markdown("<hr>")) # tag between outputs
ip_display(Markdown("### %s" % str(k)))
self[k].display_output(output_name)
def display(self, snaps=None, keys=None, header=True, raise_error=False):
"""
Display snaps as markdown structed outputs.
Parameters
----------
snaps : str or iterable[str] (optional)
the snaps to display as outputs
keys : str or iterable[str] (optional)
notebook keys to use in framing the scrapbook displays
header : bool (default: True)
indicator for if the snaps should have headers
raise_error : bool (default: False)
flag for if errors should be raised on missing output_names
"""
if isinstance(snaps, string_types):
snaps = [snaps]
if keys is None:
keys = self._notebooks.keys()
elif isinstance(keys, string_types):
keys = [keys]
for i, k in enumerate(keys):
if header:
if i > 0:
ip_display(Markdown("<hr>")) # tag between outputs
ip_display(Markdown("### {}".format(k)))
if snaps is None:
names = self[k].snaps.keys()
else:
names = snaps
for name in names:
if header:
ip_display(Markdown("#### {}".format(name)))
self[k].resketch(name, raise_error=raise_error)
def interact_fun(**kwargs):
nonlocal is_initialized
nonlocal last_cbox_value
nonlocal last_fmin_result
widget_var_values = np.array([kwargs[repr(var_symbol)] for var_symbol in self.variables])
cbox_solve_constraints = kwargs.get("chk_solve_constraints", False)
print("widget_var_values:", widget_var_values, "cbox:", cbox_solve_constraints)
if solve_constraints and cbox_solve_constraints:
free_var_values = [kwargs[repr(var_symbol)] for var_symbol in free_vars]
# initialize the dep_var_values form widgets if we have no result yet or if the checkbox was unchecked
if last_fmin_result is None:
dep_var_values = widget_var_values[dependent_var_indices]
x0_dep_vars = dep_var_values
else:
x0_dep_vars = last_fmin_result
# dict lookup with the arguments of min_target
# does not work because we never come to see this key again
# key_tuple = (tuple(np.round(x0_dep_vars, decimals=5)), tuple(free_var_values))
key_tuple = tuple(free_var_values)
cache_content = fmin_cache.get(key_tuple)
print("cache:", key_tuple, cache_content)
if caching and cache_content is not None:
dep_var_values_result = cache_content
else:
print("calling fmin with x0=", x0_dep_vars, "args=", free_var_values)
res = fmin(min_target_func, x0=x0_dep_vars, args=(free_var_values,), full_output=True)
dep_var_values_result, fopt, n_it, fcalls, warnflag = res
# fill the cache if we had these arguments for the first time (and no error occurred)
if caching and warnflag == 0:
fmin_cache[key_tuple] = dep_var_values_result
last_fmin_result = dep_var_values_result
all_vars[free_var_indices] = free_var_values
all_vars[dependent_var_indices] = dep_var_values_result
variables_values = all_vars * 1.0
# print all coordinates, convert to list for easy copy-pasting (commas)
print("all coordinates:", list(variables_values))
else:
# just use the values from the widgets
variables_values = widget_var_values
# reset the cache if checkbox is deactivated
fmin_cache.clear()
last_fmin_result = None
if not is_initialized:
self.plot_init(variables_values, axes)
is_initialized = True
last_cbox_value = cbox_solve_constraints
self.plot_update(variables_values, axes)
ip_display(fig)
def glue(name, scrap, encoder=None, display=None):
"""
Records a scrap (data value) in the given notebook cell.
The scrap (recorded value) can be retrieved during later inspection of the
output notebook.
The data type of the scraps is implied by the value type of any of the
registered data encoders, but can be overwritten by setting the `encoder`
argument to a particular encoder's registered name (e.g. `"json"`).
This data is persisted by generating a display output with a special media
type identifying the content storage encoder and data. These outputs are not
visible in notebook rendering but still exist in the document. Scrapbook
then can rehydrate the data associated with the notebook in the future by
reading these cell outputs.
Example
-------
sb.glue("hello", "world")
sb.glue("number", 123)
sb.glue("some_list", [1, 3, 5])
sb.glue("some_dict", {"a": 1, "b": 2})
sb.glue("non_json", df, 'arrow')
The scrapbook library can be used later to recover scraps (recorded values)
from the output notebook
nb = sb.read_notebook('notebook.ipynb')
nb.scraps
Parameters
----------
name: str
Name of the value to record.
scrap: any
The value to record.
encoder: str (optional)
The name of the handler to use in persisting data in the notebook.
display: any (optional)
An indicator for persisting controlling displays for the named record.
"""
# TODO: Implement the cool stuff. Remote storage indicators?!? Maybe remote media type?!?
# TODO: Make this more modular
# TODO: Use translators to determine best storage type
# ...
if not encoder:
if isinstance(scrap, string_types):
encoder = "text"
elif isinstance(scrap, (list, dict)):
encoder = "json"
else:
# This may be more complex in the future
encoder = "json"
# TODO: default to 'display' encoder when encoder is None and object is a display object type?
if display is None:
display = encoder == "display"
# Only store data that can be stored (purely display scraps can skip)
if encoder != "display":
data, metadata = _prepare_ipy_data_format(
name,
scrap_to_payload(
encoder_registry.encode(Scrap(name, scrap, encoder))),
encoder,
)
ip_display(data, metadata=metadata, raw=True)
# Only display data that is marked for display
if display:
display_kwargs = {}
if isinstance(display, (list, tuple)):
display_kwargs = {"include": display}
elif isinstance(display, dict):
display_kwargs = display
raw_data, raw_metadata = IPython.core.formatters.format_display_data(
scrap, **display_kwargs)
data, metadata = _prepare_ipy_display_format(name, raw_data,
raw_metadata)
ip_display(data, metadata=metadata, raw=True)
def scraps_report(self,
scrap_names=None,
notebook_names=None,
include_data=False,
headers=True):
"""
Display scraps as markdown structed outputs.
Parameters
----------
scrap_names : str or iterable[str] (optional)
the scraps to display as reported outputs
notebook_names : str or iterable[str] (optional)
notebook names to use in filtering on scraps to report
include_data : bool (default: False)
indicator that data-only scraps should be reported
header : bool (default: True)
indicator for if the scraps should render with a header
"""
# Keep slow import lazy
from IPython.display import display as ip_display, Markdown
def trim_repr(data):
# Generate a small data representation for display purposes
if not isinstance(data, string_types):
data_str = repr(data)
if len(data_str) > 102:
data_str = data_str[:100] + "..."
return data_str
if isinstance(scrap_names, string_types):
scrap_names = [scrap_names]
scrap_names = set(scrap_names or [])
if notebook_names is None:
notebook_names = self._notebooks.keys()
elif isinstance(notebook_names, string_types):
notebook_names = [notebook_names]
for i, nb_name in enumerate(notebook_names):
notebook = self[nb_name]
if headers:
if i > 0:
ip_display(Markdown("<hr>")) # tag between outputs
ip_display(Markdown("### {}".format(nb_name)))
for name in scrap_names or notebook.scraps.display_scraps.keys():
if headers:
ip_display(Markdown("#### {}".format(name)))
notebook.reglue(name, raise_on_missing=False, unattached=True)
if include_data:
for name, scrap in scrap_names or notebook.scraps.data_scraps.items(
):
if scrap.display is None and scrap.data is not None:
if headers:
ip_display(Markdown("#### {}".format(name)))
ip_display(trim_repr(scrap.data))
else:
ip_display("{}: {}".format(scrap.name,
trim_repr(scrap.data)))
def glue(name, scrap, storage=None):
"""
Records a scrap (data value) in the given notebook cell.
The scrap (recorded value) can be retrieved during later inspection of the
output notebook.
The storage format of the scraps is implied by the value type any registered
data translators, but can be overwritten by setting the `storage` argument
to a particular translator's registered name (e.g. `"json"`).
This data is persisted by generating a display output with a special media
type identifying the content storage format and data. These outputs are not
visible in notebook rendering but still exist in the document. Scrapbook
then can rehydrate the data associated with the notebook in the future by
reading these cell outputs.
Example
-------
sb.glue("hello", "world")
sb.glue("number", 123)
sb.glue("some_list", [1, 3, 5])
sb.glue("some_dict", {"a": 1, "b": 2})
sb.glue("non_json", df, 'arrow')
The scrapbook library can be used later to recover scraps (recorded values)
from the output notebook
nb = sb.read_notebook('notebook.ipynb')
nb.scraps
Parameters
----------
name: str
Name of the value to record.
scrap: any
The value to record.
storage: str (optional)
The data protocol name to respect in persisting data
"""
# TODO: Implement the cool stuff. Remote storage indicators?!? Maybe remote media type?!?
# TODO: Make this more modular
# TODO: Use translators to determine best storage type
# ...
if not storage:
if isinstance(scrap, string_types):
storage = "unicode"
elif isinstance(scrap, (list, dict)):
storage = "json"
else:
# This may be more complex in the future
storage = "json"
data = {
GLUE_OUTPUT_PREFIX
+ storage: {name: translator_registry.translate_data(storage, scrap)}
}
# IPython.display.display takes a tuple of objects as first parameter
# `http://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display`
ip_display(data, raw=True)
def glue(name, data, encoder=None, display=None):
"""
Records a data value in the given notebook cell.
The recorded data value can be retrieved during later inspection of the
output notebook.
The data type of the scraps is implied by the value type of any of the
registered data encoders, but can be overwritten by setting the `encoder`
argument to a particular encoder's registered name (e.g. `"json"`).
This data is persisted by generating a display output with a special media
type identifying the content storage encoder and data. These outputs are not
visible in notebook rendering but still exist in the document. Scrapbook
then can rehydrate the data associated with the notebook in the future by
reading these cell outputs.
Example
-------
sb.glue("hello", "world")
sb.glue("number", 123)
sb.glue("some_list", [1, 3, 5])
sb.glue("some_dict", {"a": 1, "b": 2})
sb.glue("non_json", df, 'arrow')
The scrapbook library can be used later to recover scraps (recorded values)
from the output notebook
nb = sb.read_notebook('notebook.ipynb')
nb.scraps
Parameters
----------
name: str
Name of the value to record.
data: any
The value to record. This must be an object for which an encoder's
`encodable` method returns True.
encoder: str (optional)
The name of the handler to use in persisting data in the notebook.
display: any (optional)
An indicator for persisting controlling displays for the named record.
"""
# Keep slow import lazy
import IPython
from IPython.display import display as ip_display
# TODO: Implement the cool stuff. Remote storage indicators?!? Maybe remote media type?!?
if not encoder:
try:
encoder = encoder_registry.determine_encoder_name(data)
except NotImplementedError:
if display is not None:
# Do not raise an exception if the scrap isn't encodable because
# the corresponding display object may be.
encoder = 'display'
else:
raise
if display is None:
display = encoder == "display"
# Only store data that can be stored (purely display scraps can skip)
if encoder != "display":
ipy_data, metadata = _prepare_ipy_data_format(
name,
scrap_to_payload(
encoder_registry.encode(Scrap(name, data, encoder))), encoder)
ip_display(ipy_data, metadata=metadata, raw=True)
# Only display data that is marked for display
if display:
display_kwargs = {}
if isinstance(display, (list, tuple)):
display_kwargs = {"include": display}
elif isinstance(display, dict):
display_kwargs = display
raw_data, raw_metadata = IPython.core.formatters.format_display_data(
data, **display_kwargs)
data, metadata = _prepare_ipy_display_format(name, raw_data,
raw_metadata)
ip_display(data, metadata=metadata, raw=True)
