Embedding Cells
The embed function is the backbone of Observable-Jupyter and the only function you will need to get stunning visualizations to populate on your screen.
To begin embedding Observable Visualizations into your project you will first import the function from Observable-Jupyter.
from observable_jupyter import embed
Note
Embed Function
- embed(partial_URL, cell=[''], inputs={'': None})
- Parameters:
partial_URL (str) – Parital URL from an Observable Notebook.
cell (list[str] or None) – Optional – cells to be displayed.
inputs (dict(str : None) or None) – Optional – variables to be manipulated.
- Returns:
Observable Visualization
- Return type:
svg
Note
If no parameters are passed for cell the entire Observable Notebook will become embedded into your project. Additionaly, if no parameters are passed for inputs the values assigned in the Observable Notebook will be used.
Rendering Visualizations
To render visualizations in a project call the embed function and pass in the desired arguments.
For this example we want to use a visualization found in the following Observable notebook: https://observablehq.com/@mbostock/epicyclic-gearing.
Important
Unsure as to where the URL being used came from? Make sure to read the Relating Observable to Observable-Jupyter section to learn about Observable and how it relates to Observable-Jupyter.
from observable_jupyter import embed
embed('@mbostock/epicyclic-gearing',
cells=['graphic'],
inputs={'speed': 0.2}
)
So what did that code just do?
First we imported the embed function
Next we called the function and passed in three arguments
The first is the path for the desired notebook we want to embed from
Then the second argument defines what cells from the notebook notebook we want to render
Finaly the third argument allows us to define values for public variables found in the notebook
To play around with the code yourself check out this link to a Google Colabs notebook with the code found on this page: Embedding Cells Demo
Note
Notice how the first argument is everything that comes after https://observablehq.com/ in the URL https://observablehq.com/@mbostock/epicyclic-gearing.
Modifying Variables
Once you know how to use the embed function it could be fun to start playing arround with variables to change aspects of your visualization.
To get the most out the ability to change variables you need to know a little bit about the observable notebook you are chosing to embed in your code. In particular you should try to get familiar with what exposed variables effect the visualization.
Tip
If going into Observable and deciphering what each variable does seems a little too daunting, take a look at the Visualization Library. There we have done the heavy lifting of exposing all necessary variables and explaining what they do.
While this is useful for common visualizations it can be limiting if you want to fully costomize a visualization.
Take the example from the embedding demo. If we look into the Observable notebook we learn that there are many variables that will change the visualization:
|
|
By including exposed variables in our inputs parameter we have the ability to modify their values and ultimately alter the behaviour of our visualization.
from observable_jupyter import embed
embed('@mbostock/epicyclic-gearing',
cells=['graphic'],
inputs={'speed': 0.2,
'toothRadius' : 0.01,
'holeRadius' : 0.03,
'frameAngle' : 22
}
)
Try this out for yourself by playing around with the modified code on the Google Colabs Notebook linked here: Modifying Variables Demo
Next Steps
For example given any visualization you have the ability to inject your own data by modifying a few variables. Depending on the visualization and how it was originaly written in Observable getting a functioning visualization after modifing variables can become a bit chalenging.