31:T4e4,md`## Observable runs a superset of JavaScript Most Jupyter users use the Python kernel, although there are kernels for [JavaScript](https://github.com/yunabe/tslab), [Julia](https://github.com/JuliaLang/IJulia.jl), [Haskell](https://github.com/gibiansky/IHaskell), too. You can also write some JavaScript in Jupyter that gets executed in the browser, but typically code in Jupyter notebooks is written in the kernel language and executed in a remote process running the kernel. For the rest of this tutorial I’ll assume familiarity with Python in a Jupyter notebook. To get the most out of Observable you’ll need some exposure to JavaScript. Our favorite full course on the language is [Eloquent JavaScript](https://eloquentjavascript.net/2nd_edition/), but if you want to leverage your Python knowledge to quickly learn some essentials, here’s a [list of differences between the languages](https://observablehq.com/d/5e82392bae5fb729). That said, if you’re experienced with Python you may be able to jump in and look for differences as you go. Observable’s [flavor of JavaScript is a little bit different](https://observablehq.com/@observablehq/observables-not-javascript), so even folks familiar with JavaScript have something to learn.`32:T4d8,md`[Like a spreadsheet](https://observablehq.com/@observablehq/how-observable-runs), Observable keeps track of which cells depend on the output of other cells and recalculates results as necessary to keep everything up to date. Have you ever worked in a notebook where something early in an analysis pipeline was changed, but you forgot to rerun later cells? In Jupyter notebooks it’s important to remember to rerun cells that depend on cells that have been changed; when teaching Jupyter to scientists, I say “you’re not done until you’ve rerun the notebook and gotten the same result,” since a key motivation for notebook computing is reproducibility. This how the creator of Jupyter, Fernando Pérez, [describes the problem](https://arxiv.org/abs/1810.08055): > Because notebooks’ interactivity make them vulnerable to accidental overwriting or deletion of critical steps by the user, if your analysis runs quickly, make a habit of regularly restarting your kernel and re-running all cells to make sure you did not accidentally delete a step while cleaning your notebook (and if you did, retrieve the code for it from version control). So using Jupyter as a fastidious data scientist requires clicking this button a lot:`33:T56e,md`## Notebooks live on the web Observable notebooks are written, edited, shared, and published entirely on the web. This enables: - **One-click sharing. ** Like remotely hosted Jupyter notebooks, Observable notebooks can be shared by clicking “Publish” in the top right **⋯** menu, either with the world by clicking more selectively by private link or with specific Observable users. Collaborators can of course make changes to the notebook if given permission. Viewers can also try out their own changes, suggest those changes be made in the original, or fork the notebook to save their changes and go their own way with the code. Maybe they’ll substitute their own data! - **Instant boot.** Unlike many hosted Jupyter notebooks platforms, there’s no waiting for the kernel and environment to initialize, e.g. waiting for a Docker container to spin up. Since notebooks run in the browser, viewers can immediately run them, interact with inputs, and try out changes to the code locally. - **Download or embed.** If you’d rather share a visualization without showing code you can [embed a cell in another website](https://observablehq.com/@observablehq/downloading-and-embedding-notebooks) which doesn’t show the notebook editor UI. And similarly to exporting a Jupyter notebook as a .py file, you can download notebook code as a module to use from other JavaScript code.`34:T6fa,md`## Code runs in your browser Observable code running in your browser’s JavaScript engine is different from Jupyter code running in a separate kernel process: for instance, you can use your browser’s dev tools to debug your code. - **Respond to user interaction in milliseconds.** Without a client–server roundtrip, notebooks can react very fast to code changes or interactive widget changes. Running a piece of code 30, 60, or 120 times a second to make a smooth animation is very normal use case, as is recalculating a visualization based on a slider a user is whipping back and forth. - **New web superpowers.** Use libraries like [D3](https://observablehq.com/@d3) and [browser APIs](https://developer.mozilla.org/en-US/docs/Web/API) like [WebGL](https://observablehq.com/collection/@observablehq/webgl) to build rich interactive experiences. Stream video, make HTTP calls to APIs, use multi-touch controls, play audio, use WebAssembly and more! Observable is a great platform for using JavaScript, HTML, CSS, and SVG without needing to setting up your editor, module bundler, compiler toolchain, etc. - **What’s my process ID?** You can’t get the current process ID in Observable. You can’t directly open a TCP socket, you can’t access the filesystem, you can’t shell out to run a bash command, and you can’t dynamically load binaries. Sometimes this changes the way you write your notebooks. Syscalls your browser vendor didn’t intend for you to make are off-limits. The browser sandbox lets you run notebook code you don’t trust, unlike a local Jupyter kernel (but similar to Jupyter in a Docker container or hosted environment like Binder). Your web browser is a hardened environment that runs hundreds of untrusted pieces of code before breakfast.`35:T5c9,md`## You can import cells from other notebooks Although [workflows for reusing values from other Jupyter notebooks exist](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Importing%20Notebooks.html), the idiomatic way to reuse code is to import functionality from factored-out modules or from packages installed from PyPI. In Observable it’s common to use \`import\` to reuse functions and values from other notebooks, in addition to using \`require\` to pull in JavaScript packages from registries like npm and GitHub. Since these modules are pulled from the internet, there’s no separate installation step; just \`require\` the code you need. Importing a module in Python means executing a module (a file), then assigning particular objects in that namespace to variables. This is fine in the normal case, when the other module is all function and class definitions, but notebooks often include code top-level code you wouldn’t necessarily want to run on import. Importing a cell from another Observable notebook only runs the cells needed to produce the imported value, e.g. you can import just a file attachment from another notebook and know that data processing and animations in the notebook are not running in the background. This notebook includes keyboard shortcuts that are different on Mac, so we import a helper utility that checks the viewer’s browser for OS so we can show “option” for Mac and “meta” for Windows and Linux: `36:[{"id":"5223529d5267a98fd4dd078909ef115581579d445bbeee474a1a91640ea045239d3ac00a2e80a03a5c1614f2bada16662ed7c870126a8bac14498afd4cdbcf4b","href":"https://static.observableusercontent.com/files/5223529d5267a98fd4dd078909ef115581579d445bbeee474a1a91640ea045239d3ac00a2e80a03a5c1614f2bada16662ed7c870126a8bac14498afd4cdbcf4b","name":"2020-01-30 10.08.32.gif","type":"image/gif","lastModified":1580407800693.092,"size":411253},{"id":"0b128af7ebd0e880b68101f514a120f60e0672cfa13ee9cdd7a968c282caa70542c55fed403cf3664586d93202df381fd28bfa1895dec93cd7e33a6ce1130b13","href":"https://static.observableusercontent.com/files/0b128af7ebd0e880b68101f514a120f60e0672cfa13ee9cdd7a968c282caa70542c55fed403cf3664586d93202df381fd28bfa1895dec93cd7e33a6ce1130b13","name":"jupyter.png","type":"image/png","lastModified":1578440026641.323,"size":117703},{"id":"78c5827477ecd1ce684a74324225a8cc7b2370a279dbe0892159bd52c60496207aabc8dfbf4f914e690761e18a344de8f3e5e03c440e18ee065e191c77b884f3","href":"https://static.observableusercontent.com/files/78c5827477ecd1ce684a74324225a8cc7b2370a279dbe0892159bd52c60496207aabc8dfbf4f914e690761e18a344de8f3e5e03c440e18ee065e191c77b884f3","name":"2020-03-02 10.29.45.gif","type":"image/gif","lastModified":1583173849249.135,"size":220653},{"id":"c86aff95dc0d2a4d4d5fdc57c2ab46295b790ec90b5bfad3196ca30726842c55baca1123b01587fb8a0f15524d9219bd98d8fed716be8e0c8f698d21e71de67a","href":"https://static.observableusercontent.com/files/c86aff95dc0d2a4d4d5fdc57c2ab46295b790ec90b5bfad3196ca30726842c55baca1123b01587fb8a0f15524d9219bd98d8fed716be8e0c8f698d21e71de67a","name":"cell_modes.png","type":"image/png","lastModified":1645829510483.859,"size":17954}] 2f:{"title":"Observable for Jupyter Users","cells":[{"id":0,"value":"md`# Observable for Jupyter Users\n\nObservable, like Jupyter, is a computational notebook that’s great for doing data science and visualization, where “notebook” refers to a series of cells containing prose, code, and visualizations. Observable runs a superset of JavaScript entirely in your browser, so it draws on a different ecosystem than the Python one you may be used to. This tutorial shows Jupyter users how to make the most of Observable.\n\nLet’s start with the big differences.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":674,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":5,"value":"md`## Cell outputs are shown *above* the code`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1477,"value":"md`In Observable the output of a cell — be it a visualization, an object, or any other result of an expression — comes first. The code that produces it appears below.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":9,"value":"2 ** 3","pinned":true,"hidden":false,"mode":"ojs"},{"id":14,"value":"md`## You can show or hide the code`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2476,"value":"{\n const text = 'The code in a newly created cell begins pinned, which keeps it visible, but cells can be unpinned so their code is hidden. To see the code again, click the space to the left of the cell output.'\n return md`${text}\n\n>

`\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1691,"value":"md`Try it: click the empty space to the left of the cell below to see the code for it, then click the thumbtack icon to keep it visible when you open another cell.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1489,"value":"9 + 8","pinned":false,"hidden":false,"mode":"ojs"},{"id":1545,"value":"md`This gives you more control over the presentation of your notebook: if you want to call attention to way a result was produced, you can leave the cell pinned for all to see. Otherwise unpin the cell so the code is still available, waiting for a curious viewer to reveal it underneath.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2207,"value":"md`## Use shift-enter to run a cell\n\nIf you’re used to running a cell with ${\n mac ? \"option-enter\" : \"alt-enter\"\n} in Jupyter, you may be surprised to find that this *splits* cells in Observable. For more, check out the [keyboard shortcuts](https://observablehq.com/@observablehq/keyboard-shortcuts) notebook or click the ? button on the right and scroll down to the list of keyboard shortcuts.\n\nYou can use cmd-enter to get the behavior of option-enter in Jupyter of running a cell and inserting another directly below.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1996,"value":"md`## Cells produce only one value`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1728,"value":"md`Like function bodies in JavaScript, cells in Observable are either a single expression or a block of statements. Cells with a single expression evaluate to the result of that expression.\n\nSimilar to the way only the last expression in a Jupyter notebook has its \\`repr()\\` printed below the cell, only one expression is returned from a cell with multiple statments. Instead of something akin to an implicit return of the final statement, Observable blocks use a return statement to specify this value. If no value is returned, similar to ending the last statement in Jupyter with a semicolon, the cell evaluates to \\`undefined\\`.\n\nTo write multiple statements in a cell instead of a single expression, you need to surround the code with curly brackets to make it a code block. Use a return statement to specify the value of a code block.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1704,"value":"{\n const foo = (x) => x + 1;\n const arr = [1,2,3];\n return arr.map(foo);\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":2321,"value":"md`If you just want an object literal (which looks like a dictionary in Python), you must distinguish it from a block by wrapping it in parentheses:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2322,"value":"({hello: \"world\"})","pinned":true,"hidden":false,"mode":"ojs"},{"id":30,"value":"md`## Variables defined inside a block can only be accessed inside that block\nInside the block, any declared variables will be local variables and you’ll need to use \\`let\\` or \\`const\\` to declare them. Cell blocks are similar to bodies of functions in this way. Here, \\`radius\\` is not accessible from other cells:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":32,"value":"{\n const radius = 12;\n return 2 * Math.PI * radius;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":2117,"value":"Math.PI * radius ** 2","pinned":true,"hidden":false,"mode":"ojs"},{"id":1985,"value":"md`## Cells can be named`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1988,"value":"md`To make the return value of a cell available to code in other cells, you can name the cell, i.e. assign it to a special kind of global variable. This does not use \\`var\\`, \\`const\\`, or \\`let\\`; just write the name and equals:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1730,"value":"z = 123 + 456","pinned":true,"hidden":false,"mode":"ojs"},{"id":1965,"value":"md`The code defines \\`z\\` as \\`123 + 456\\`. You can now reference \\`z\\` like any other variable in code anywhere else in the notebook. Because every cell has just one return value, you should break up big cells into little, focused ones.\n\nAs a special kind of global variable, it gets some special treatment.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":36,"value":"md`## Observable is reactive\nThis is the biggest difference between the evaluation model of Observable and Jupyter. If you fight it, you will get a headache; if you learn it, you will find what makes this notebook magical:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2138,"value":"{\n const str = \"Cells re-run automatically!\"\n return html`

\n ${str.split(\"\").map((char, i) => html`${char}`)}\n

`\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":100,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":39,"value":"md`

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":44,"value":"md`In Observable, this happens automatically, every time a referenced value changes.\n\nYou can think of Observable keeping cells up to date as killing the kernel and rerunning the whole notebook each time you edit a cell, or you can think of it as rerunning just the cells that depend on the cell you’re editing (which is what’s actually happening).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":88,"value":"md`This is a very different tradeoff than Jupyter makes! Observable’s approach is helpful for quickly iterating on visualizations or other outputs built up over multiple cells, and when a value is used in multiple places in a notebook. Not needing to remember to rerun the right cells is one less thing to worry about while focusing on a notebook’s contents.`\n","pinned":false,"hidden":false,"mode":"ojs"},{"id":46,"value":"md`These special, Notebook-level variables can only be defined once, and cannot be reassigned:`\n","pinned":false,"hidden":false,"mode":"ojs"},{"id":235,"value":"a = 10","pinned":true,"hidden":false,"mode":"ojs"},{"id":236,"value":"a = 11","pinned":true,"hidden":false,"mode":"ojs"},{"id":210,"value":"md`And you cannot define a cell circularly:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":239,"value":"b = c + 1","pinned":true,"hidden":false,"mode":"ojs"},{"id":240,"value":"c = b + 2","pinned":true,"hidden":false,"mode":"ojs"},{"id":1895,"value":"md`The upside is that user interactions and changes to code propagate instantly. There’s no need to rerun other cells! Change \\`bits\\` below and \\`maxSignedInt\\` will update too.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1766,"value":"bits = 18 // change this number and press shift-enter to run!","pinned":true,"hidden":false,"mode":"ojs"},{"id":1771,"value":"maxSignedInt = 2 ** (bits - 1) - 1","pinned":true,"hidden":false,"mode":"ojs"},{"id":1833,"value":"\nmd`## Cells don’t run from top to bottom\n\nBecause the order of cells in a notebook doesn’t affect the execution order, Observable notebooks are structured in whatever order makes most sense to the author. They often show a final result at the top and expand on the subparts of the problem below.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":107,"value":"md`In this adaptation of Ned Batchelder’s venerable [pizza.py](https://nedbatchelder.com/blog/201210/pizzapy.html), the shopping list at the top uses the input slider, constants, and import defined below.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":109,"value":"md`**We need ${'🍕'.repeat(meat)} meat, ${'🍕'.repeat(veggie)} veggie, ${'🍕'.repeat(vegan)} vegan.**`","pinned":true,"hidden":false,"mode":"ojs"},{"id":2831,"value":"viewof rsvps = Inputs.range([0, 100], {label: \"RSVPs\", step: 1})","pinned":true,"hidden":false,"mode":"ojs"},{"id":115,"value":"meat = Math.floor(0.4 * pies) || 1","pinned":true,"hidden":false,"mode":"ojs"},{"id":122,"value":"vegan = Math.floor(0.15 * pies) || 1","pinned":true,"hidden":false,"mode":"ojs"},{"id":148,"value":"veggie = Math.floor(0.45 * pies) || 1","pinned":true,"hidden":false,"mode":"ojs"},{"id":49,"value":"pies = Math.round(people * 2.5 / 8);","pinned":true,"hidden":false,"mode":"ojs"},{"id":134,"value":"people = Math.round(rsvps * .65) // the Meetup Universal Constant","pinned":true,"hidden":false,"mode":"ojs"},{"id":2235,"value":"## Cell Modes\n\nAny cell in Observable can use one of multiple cell modes for JavaScript, Markdown, HTML, TeX, and several other types.","pinned":false,"hidden":false,"mode":"md"},{"id":2795,"value":"

\n \n

Each cell can use one of the available cell modes.

\n","pinned":false,"hidden":false,"mode":"html"},{"id":2710,"value":"Cells in JavaScript mode (the default) can hold values or expressions:","pinned":false,"hidden":false,"mode":"md"},{"id":2274,"value":"\"hello world\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":2740,"value":"22/7","pinned":true,"hidden":false,"mode":"ojs"},{"id":1503,"value":"Cells in JavaScript mode also can contain Objects:","pinned":false,"hidden":false,"mode":"md"},{"id":641,"value":"({\n a: 100,\n b: 200,\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":16,"value":"Observable includes [standard library](https://observablehq.com/@observablehq/standard-library) functions that return DOM nodes, to make it easy to create rich documents with text and graphics.","pinned":false,"hidden":false,"mode":"md"},{"id":1507,"value":"md`HTML DOM nodes:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":621,"value":"{\n const div = document.createElement('div')\n div.innerText = 'This is a DIV'\n div.style.border = 'solid 10px gray';\n div.style.textAlign = 'center';\n div.style.width = '200px';\n return div;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":25,"value":"html`

This is a DIV`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2305,"value":"md`Write SVG with the [\\`svg\\`](https://github.com/observablehq/stdlib/blob/master/README.md#svg) tagged template literal:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2306,"value":"svg``","pinned":true,"hidden":false,"mode":"ojs"},{"id":2299,"value":"md`Write markdown with the [\\`md\\`](https://github.com/observablehq/stdlib#markdown) tagged template literal:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2717,"value":"Write Markdown with the Markdown cell mode:","pinned":false,"hidden":false,"mode":"md"},{"id":608,"value":"This ~~txet~~ *text* is rendered as Markdown.","pinned":true,"hidden":false,"mode":"md"},{"id":2750,"value":"Write HTML with the `html` cell mode:","pinned":false,"hidden":false,"mode":"md"},{"id":2745,"value":"

This is a DIV","pinned":true,"hidden":false,"mode":"html"},{"id":1678,"value":"Write ${tex`\\LaTeX`} with the `TeX` cell mode:","pinned":false,"hidden":false,"mode":"md"},{"id":1633,"value":"tex`-b \\pm \\sqrt{b^2 - 4ac} \\over 2a`","pinned":true,"hidden":false,"mode":"ojs"},{"id":2726,"value":"-b \\pm \\sqrt{b^2 - 4ac} \\over 2a","pinned":true,"hidden":false,"mode":"tex"},{"id":2779,"value":"There is also a SQL cell mode; see [SQL cells](https://observablehq.com/@observablehq/sql-cells) for examples.","pinned":false,"hidden":false,"mode":"md"},{"id":622,"value":"md`If you’re familiar with the IPython [\\`display()\\`]() function, which renders content to the notebook based on its type, it might be helpful to imagine that the output shown above an Observable cell is the result of calling \\`display()\\` on the result of running the cell code.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1746,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":658,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":1020,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":903,"value":"import {mac} from '@mbostock/keys'","pinned":false,"hidden":false,"mode":"ojs"},{"id":2340,"value":"md`That’s just a simple utility, but you can also import entire interactive visualizations. For example, there are [hundreds of D3 examples](https://observablehq.com/@d3/gallery) ready for you to import.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1074,"value":"md`---\n\nThe combination of living on the web, reactive coding, and cell imports makes Observable a uniquely dynamic community of collaborative creative coders. Now you’re ready to import, analyze, and visualize a dataframe in Observable.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2356,"value":"html`Next`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W36","stdlib":"1","titling":"auto"}