31:[{"id":"f1f1344c5afd87a7d173bcfc688ba86da5588220c84ca31d62db89d871459beb953cc9b864301a350744e637e9caff4107edebe51f88687fec6bf96903bde65e","href":"https://static.observableusercontent.com/files/f1f1344c5afd87a7d173bcfc688ba86da5588220c84ca31d62db89d871459beb953cc9b864301a350744e637e9caff4107edebe51f88687fec6bf96903bde65e","name":"d3.json","type":"application/octet-stream","lastModified":1572391116658.268,"size":21848},{"id":"73ddce2cd17424eb0f4ea8b4518d0970ce88543512a0bf818f26187a44960ce1b786eabc874e6b565f3bd1f16b5f5a99f4623b145bb38504c9176a8d8c94d165","href":"https://static.observableusercontent.com/files/73ddce2cd17424eb0f4ea8b4518d0970ce88543512a0bf818f26187a44960ce1b786eabc874e6b565f3bd1f16b5f5a99f4623b145bb38504c9176a8d8c94d165","name":"cellNamingMarkdown.png","type":"image/png","lastModified":1654618320983.098,"size":24514}] 2f:{"title":"Introduction to imports","cells":[{"id":0,"value":"md`# Introduction to imports\n\nObservable lets you quickly reuse code by importing named cells from other notebooks.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":772,"value":"## Example of Importing a Function","pinned":false,"hidden":false,"mode":"md"},{"id":771,"value":"md`Let’s say you saw Mike Bostock's notebook of [color scales](https://observablehq.com/@mbostock/color-ramp) used to visualize quantitative data. That notebook defines a \\`ramp\\` function that returns a canvas for a given \\`color\\` function, where the \\`color\\` function returns a color for a given ${tex`t \\in [0,1]`} from left to right. To create the dreaded angry rainbow yourself, import and call \\`ramp\\`:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":74,"value":"import {ramp} from \"@mbostock/color-ramp\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":77,"value":"ramp(t => `hsl(${t * 360}, 100%, 50%)`)","pinned":true,"hidden":false,"mode":"ojs"},{"id":770,"value":"**Note**: For the source of the `import` statement, use the Observable username and notebook name; that is:\n\n`from` @_username_/_notebookName_\n\nYou can get these from the URL of the notebook from which you are importing.","pinned":false,"hidden":false,"mode":"md"},{"id":769,"value":"## Why Import vs. Copy-Paste?","pinned":false,"hidden":false,"mode":"md"},{"id":89,"value":"md`You could instead copy-paste the \\`ramp\\` function from that notebook into this one—it’s only a few lines of code. But imports have a few advantages.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":767,"value":"### Cell Dependencies","pinned":false,"hidden":false,"mode":"md"},{"id":766,"value":"First, the cell you want to reuse may depend on other cells. If you copy-paste, you have to copy-paste those other cells too, and make sure that they don’t conflict with existing cells in your notebook. If you import, the dependencies are loaded automatically, so you don’t have to think about it.\n\nFor example, consider a notebook on an interrupted Sinu–Mollweide map projection that requires the D3 and TopoJSON libraries, along with geometry representing the Earth’s landmasses. You can import the map and display it without worrying about how the sausage is made.","pinned":false,"hidden":false,"mode":"md"},{"id":93,"value":"import {map} from \"@d3/interrupted-sinu-mollweide\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":97,"value":"map","pinned":true,"hidden":false,"mode":"ojs"},{"id":765,"value":"### Re-used Code Stays Up-to-Date","pinned":false,"hidden":false,"mode":"md"},{"id":314,"value":"Second, by importing, it’s easier to keep the reused code up-to-date. Imports target the latest version, so if Mike improves his map notebook, the new map will automatically appear here.\n\n(The risk of importing the latest version is that your notebook may break if the imported notebook changes in a non-backwards-compatible way. Observable has version locking, which allows you to \"lock\" the version of the notebook you are importing. See [Version Locking for Notebook Imports](https://observablehq.com/@observablehq/version-locking-for-notebook-imports?collection=@observablehq/introduction) for more details.)","pinned":false,"hidden":false,"mode":"md"},{"id":763,"value":"### \"Rewrite\" Code Using `import` - `with`","pinned":false,"hidden":false,"mode":"md"},{"id":317,"value":"md`Third, and most excitingly, Observable imports let you inject dependencies using \\`import\\`-\\`with\\`! This lets you “rewrite” imported code as you might do when copy-pasting, without the problems of code duplication.\n\nConsider Mike Bostock's D3 treemap notebook that visualizes the Flare dataset. To reuse this treemap implementation to visualize a different dataset, inject a new definition of \\`data\\` in the \\`with\\` clause on import:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":380,"value":"import {chart as treemap}\nwith {treemap_data as data}\nfrom \"@d3/treemap@164\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":386,"value":"treemap","pinned":true,"hidden":false,"mode":"ojs"},{"id":383,"value":"treemap_data = FileAttachment(\"d3.json\").json()","pinned":true,"hidden":false,"mode":"ojs"},{"id":761,"value":"As long as the new data conforms to the same shape as the old data (here, a tree of objects with *children* and *value* properties), you can reuse the existing code without copy-paste and the terrible challenge of designing a reusable chart abstraction!","pinned":false,"hidden":false,"mode":"md"},{"id":760,"value":"### Adding Dynamic Definitions to Previously Static Code","pinned":false,"hidden":false,"mode":"md"},{"id":389,"value":"md`\nBest of all, because [Observable is reactive](/@observablehq/how-observable-runs), you can even inject dynamic definitions into code that was previously static!\n\nFor example, below is a histogram of a synthetic beta distribution using ${tex`\\alpha`} and ${tex`\\beta`} values that are controlled by sliders. Whenever ${tex`\\alpha`} or ${tex`\\beta`} change, Observable automatically updates the histogram—even though the implementation is reused from a static histogram of unemployment rates.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":391,"value":"import {chart as histogram}\nwith {histogram_data as data}\nfrom \"@d3/histogram@261\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":697,"value":"viewof alphabeta = {\n const form = html``;\n form.oninput = () => {\n form.value = [form.a.valueAsNumber, form.b.valueAsNumber];\n form.oa.value = form.a.valueAsNumber;\n form.ob.value = form.b.valueAsNumber;\n };\n form.oninput();\n return form;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":394,"value":"histogram","pinned":true,"hidden":false,"mode":"ojs"},{"id":397,"value":"histogram_data = new Array(10000).fill().map(() => randb(...alphabeta))","pinned":true,"hidden":false,"mode":"ojs"},{"id":758,"value":"### Nuances When Using Imports","pinned":false,"hidden":false,"mode":"md"},{"id":113,"value":"md`Here are a few additional nuances of imports:\n\n- Like [ES imports](http://exploringjs.com/es6/ch_modules.html), Observable imports are live bindings. If you import a value that changes over time ([a generator cell](/@mbostock/generator-cells-functions-and-objects)), such as a countdown to a certain date in the future, the imported value will change over time, too.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":115,"value":"import {interval} from \"@observablehq/firstcontactcountdown\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":118,"value":"interval","pinned":true,"hidden":false,"mode":"ojs"},{"id":3,"value":"md`\n- You can only import named cells, and you must name each cell you want to import explicitly. No anonymous cells allowed; if a notebook uses side effects, as is sometimes common with anonymous cells, you must name and import the cells with side effects, too. (See [Naming Cells](#howToNameCells) for a refresher on naming cells.)\n\n- Imported cells are lazily evaluated: if you import a cell but you don’t reference it anywhere, the code won’t run. Try uncommenting the cell below and then hit Shift-Enter. Notice that the generator *i* begins at zero—it doesn’t start until referenced.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":20,"value":"// i","pinned":true,"hidden":false,"mode":"ojs"},{"id":11,"value":"import {i} from \"@observablehq/generator-cells-functions-and-objects\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":47,"value":"md`\n- Also like ES imports, only the cells you import are available (*bound*) in the local notebook, even if those cells depend on other cells. Those dependent cells are *run*—they’re just not exposed in the scope of the local notebook.\n\n- You can use circular imports, but only if you don’t use the *with* clause when importing. Import-with effectively creates a local copy of the imported module with your overrides, so a circular import-with would create an infinitely recursive module, a bit like seeing your reflection in a mirrored room.\n\n- You can import the same notebook multiple times and references will resolve exactly. (Note, however, that the versions of the imported notebooks must also match, or they are considered different notebooks.)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":561,"value":"import {map as map2} from \"@d3/interrupted-sinu-mollweide\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":564,"value":"map === map2","pinned":true,"hidden":false,"mode":"ojs"},{"id":753,"value":"### Import Visualizer for Debugging","pinned":false,"hidden":false,"mode":"md"},{"id":718,"value":"md`If you find yourself using lots of imports in your notebooks, you might find our [import visualizer](/@observablehq/notebook-import-visualizer) helpful for debugging. For example, here are the imports used by this notebook. *So meta!*`","pinned":false,"hidden":false,"mode":"ojs"},{"id":725,"value":"graph","pinned":false,"hidden":false,"mode":"ojs"},{"id":668,"value":"shared = md`### Public, Unlisted, and Private imports\n\nThe examples so far have imported from public notebooks. But you can import from unlisted notebooks, too:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":751,"value":"import {functionFromUnlistedNotebook} from \"00ff3ac693572256\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":750,"value":"functionFromUnlistedNotebook","pinned":true,"hidden":false,"mode":"ojs"},{"id":556,"value":"You can even import from private notebooks; however, private notebooks can be imported only into other private notebooks by the same owner. Imports from private notebooks won’t be accessible to your readers, which may prevent your notebook from functioning as intended.\n\nLastly, imports aren’t intended to replace libraries (like [lodash](https://lodash.com) or [D3](https://d3js.org)); if you want to design, build and support a reusable library, go for it and publish to npm! But if you want a lightweight way to reuse code across notebooks without resorting to copy-paste, reach for import.","pinned":false,"hidden":false,"mode":"md"},{"id":800,"value":"---","pinned":false,"hidden":false,"mode":"md"},{"id":749,"value":"howToNameCells = md `## Naming Cells`","pinned":false,"hidden":false,"mode":"ojs"},{"id":748,"value":"You can assign a name to a JavaScript cell in one of the four following ways:","pinned":false,"hidden":false,"mode":"md"},{"id":747,"value":"Naming a cell expression:","pinned":false,"hidden":false,"mode":"md"},{"id":746,"value":"expressionName = 8","pinned":true,"hidden":false,"mode":"ojs"},{"id":745,"value":"Naming a block:","pinned":false,"hidden":false,"mode":"md"},{"id":744,"value":"blockName = { return 80; }","pinned":true,"hidden":false,"mode":"ojs"},{"id":743,"value":"Naming a function declaration:","pinned":false,"hidden":false,"mode":"md"},{"id":742,"value":"function functionName() {return 800;}","pinned":true,"hidden":false,"mode":"ojs"},{"id":741,"value":"Naming a class:","pinned":false,"hidden":false,"mode":"md"},{"id":740,"value":"class className {}","pinned":true,"hidden":false,"mode":"ojs"},{"id":793,"value":"To name a Markdown cell, enter the name of the cell in the following area (visible at the bottom of your browser window when you are editing the cell):","pinned":false,"hidden":false,"mode":"md"},{"id":792,"value":"

\n \n

Use the highlighted area to name Markdown cells (or any other type of cell).

\n","pinned":false,"hidden":false,"mode":"html"},{"id":430,"value":"md`## Appendix`","pinned":false,"hidden":false,"mode":"ojs"},{"id":721,"value":"url = \"https://api.observablehq.com/@observablehq/introduction-to-imports.js?v=3\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":728,"value":"orient = \"LR\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":724,"value":"import {graphic as graph} with {url, orient} from \"@observablehq/notebook-import-visualizer\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":442,"value":"function randb(alpha, beta) {\n const u = randg(alpha);\n return u / (u + randg(beta));\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":443,"value":"// Returns a gamma deviate by the method of Marsaglia and Tsang.\nfunction randg(shape) {\n let oalph = shape, a1, a2, u, v, x, mat;\n if (!shape) shape = 1;\n if (shape < 1) shape += 1;\n a1 = shape - 1 / 3;\n a2 = 1 / Math.sqrt(9 * a1);\n do {\n do {\n x = randn();\n v = 1 + a2 * x;\n } while (v <= 0);\n v = v * v * v;\n u = Math.random();\n } while (\n u > 1 - 0.331 * Math.pow(x, 4) &&\n Math.log(u) > 0.5 * x * x + a1 * (1 - v + Math.log(v))\n );\n if (shape === oalph) return a1 * v; // alpha > 1\n do u = Math.random(); while (u === 0); // alpha < 1\n return Math.pow(u, 1 / oalph) * a1 * v;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":445,"value":"// Returns a normal deviate (mu=0, sigma=1).\nfunction randn() {\n let u, v, x, y, q;\n do {\n u = Math.random();\n v = 1.7156 * (Math.random() - 0.5);\n x = u - 0.449871;\n y = Math.abs(v) + 0.386595;\n q = x * x + y * (0.19600 * y - 0.25472 * x);\n } while (q > 0.27597 && (q > 0.27846 || v * v > -4 * Math.log(u) * u * u));\n return v / u;\n}","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}