In [1]:
import sys
path ="/home/sergio/github/shaolin-master"
sys.path.append(path)
Shaolin (Structure Helper for dAshbOards LINking) is a framework that aims to simplify the process of writing interactive dashboards. Shaolin can be seen as an interface that provides an additional layer of functionality to the ipywidgets library, extending its capabilities and providing en easier way to write complex GUIs composed of multiple widgets and different levels of interactivity.
This framework is build around the concept of Dashboard. A Dashboard could be interpreted as "black box" object that can be completely managed trhough a GUI comprised of widgets that will allow us to interact with its internal code. A dashboard can be used to generate an arbitrary dictionary of parameters or it can also execute an arbitrary piece of code using its GUI to manage the code parameters.
A widget is the most basic component a Dashboard can have. A Shaolin widget is just a wrapper for an ipywidgets widget to decouple the shaolin framework from ipywidgets, improve scalability and making it easier to create a new widged using a minified syntax.
Any widget compatible with the ipywidgets package can be used as a shaolin widget. Here you can fin a list of available widgets, but shaolin is also compatible with custom widgets.
A Shaolin Widget is an object that mimics the ipywidgets interface and adds additional functionality. Its displayed using its widget attribute and internally it has two main elements:
The following code is mean to illustrate the structure of a Shaolin widget:
In [2]:
from IPython.display import Image #this is for displaying the widgets in the web version of the notebook
from shaolin.core.shaoscript import shaoscript
wid = shaoscript('fs') #this creates a FloatSlider widget
type(wid.widget), type(wid.target)
Out[2]:
In [3]:
wid.target.layout.border = 'red solid'
wid.widget.layout.border = 'blue solid'
#wid.widget
Image(filename='shaolin_syntax_data/img_1.png')
Out[3]:
As all the interactive logic will be using the target attribute a set of aliases and functions have been defined in order to simplify accessing the most common widget attributes. A widget has the following aliases:
Although using shaoscript to create a widget is the recommended way of instantiating a widget this can also be done usgint the shaolin widget class directly as a wrapper for an ipywidget Widget.
A shaolin widget can be instantiated using the Widget object from the shaolin.core module. All the attributes passed besides the widget type are meant to be passed to the target widget.
In [4]:
from shaolin.core.widgets import Widget
import ipywidgets as widgets
In [5]:
class_wid = Widget(widgets.FloatSlider, description='Fs', value=15.3)
target_kwargs = {'orientation':'vertical',
'value':13.,
'description':'Example'
}
class_wid2 = Widget(widgets.FloatSlider,**target_kwargs)
#widgets.HBox(children = [class_wid2.widget,class_wid.widget])
Image(filename='shaolin_syntax_data/img_2.png')
Out[5]:
The recommended way for creating a shaolin widget is using what is called shaoscript. Shaoscript is a minified syntax that allows for faster widget creation. This can be done the following way:
In [6]:
from shaolin.core.shaoscript import shaoscript
wid = shaoscript('fs') #this creates a FloatSlider widget
#wid.widget
Image(filename='shaolin_syntax_data/img_3.png')
Out[6]:
There are two ways of creating a Shaolin widget using shaoscript:
The object notation is an extension of the syntax used for the interact function of the ipywidgets package that allows to define a numeric or boolean widget by passing a python object (a tuple or a list). this object is called an object notation word.
The syntax rules fro creating widgets using object notation are the following:
### Slider widgets
#### Data types Set by the element of the tuple containing the value parameter. Compatible types are:
#### Syntax
In [7]:
extended_islid = shaoscript(1)
compact_islid = shaoscript((0,10,1,5))
#widgets.HBox(children=[extended_islid.widget,compact_islid.widget])
Image(filename='shaolin_syntax_data/img_4.png')
Out[7]:
### Numeric text box widgets
#### Data types Set by the element of the list containing the value parameter. Compatible types are:
#### Syntax
In [8]:
extended_ftxt = shaoscript([1.])
compact_ftxt = shaoscript([0.,10.,2.16])
#widgets.HBox(children=[extended_ftxt.widget,compact_ftxt.widget])
Image(filename='shaolin_syntax_data/img_5.png')
Out[8]:
### Boolean widgets:
#### Data types: Value must be a bool.
#### CheckBox
#### ToggleButton
#### Valid
In [9]:
checkbox = shaoscript(True)
checkbx_2 = shaoscript((True,'check'))
togglebutton = shaoscript([False, 'toggle'])
valid = shaoscript([[False]])
#widgets.HBox(children=[checkbox.widget,checkbx_2.widget, togglebutton.widget,valid.widget])
Image(filename='shaolin_syntax_data/img_6.png')
Out[9]:
### Options widgets:
#### Data types
#### Dropdown
#### SelectMultiple
In [10]:
ddown = shaoscript((['opt1','opt2'],'opt1'))
selmul = shaoscript([('opt1','opt2'),('opt1',)])
#widgets.HBox(children=[ddown.widget,selmul.widget])
Image(filename='shaolin_syntax_data/img_7.png')
Out[10]:
Any Shaolin Widget can be created passing a string as a shaoscript parameter. This is the recommended way of instantiating widgets and the only way a Dashboard component can be stated. A widget can be created using its string keyword or a string which its literal evaluation is an object notation word.
Each type of widget has multiple valid aliases. The available words for defining each type of widget are:
It is also possible to set the parameters of the widgets using string notation. This way it's easier and shorter to instantiate a widget with non default params.
The syntax for writing a string notation widget with custom parameters is the following:
This means that the widget name provided as a string representation of the object notation or its string notation will be separated from the parameters by a dollar sign $ and each of the parameters will be separated by an & sign.
In a general case the name of the parameter and its value will be separated by a = sign, and the value will be a literal evaluation of the string.
There are some of the most common parameters that have special shorcuts in order to save tiem when defining a widget. These are the parameters that behave in a non default way:
Here are some examples of using a widget with shaoscript versus using the standard ipywidgets package for defining them.
In [11]:
fs_wid = widgets.FloatSlider(description='slider',
min=3.14,
max=15,
step=0.16,
value=6.0290
)
fs_shao_objn = shaoscript('(3.14,15,0.16,6.0290)$d=slider')#object notation
fs_shao_strn = shaoscript('fs$d=slider&min=3.14&max=15&step=0.16&val=6.0290')#string notation
#widgets.HBox(children=[fs_wid,fs_shao_objn.widget,fs_shao_strn.widget])
Image(filename='shaolin_syntax_data/img_8.png')
Out[11]:
It is possible to write a shorcut por creating different kinds of text widgets according to markdown syntax
In [12]:
title = shaoscript('#This is a title')
#title.widget
Image(filename='shaolin_syntax_data/img_9.png')
Out[12]:
In [13]:
title = shaoscript('##This is a subtitle')
#title.widget
Image(filename='shaolin_syntax_data/img_10.png')
Out[13]:
In [14]:
title = shaoscript('###This is strong')
#title.widget
Image(filename='shaolin_syntax_data/img_11.png')
Out[14]:
In [ ]: