|
1 | | ---- |
2 | | -description: Guide and tips to using Dnotebook. |
3 | | ---- |
| 1 | +# Dnotebook Documentation |
4 | 2 |
|
5 | | -# Getting Started |
6 | | - |
7 | | -## Installation |
8 | | - |
9 | | -To install Dnotebooks, you must have Node.js installed. If you do not have it, following the official guide here to install it. |
10 | | - |
11 | | -Once Node.js is installed, you can install Dnotebook by running the command below on a terminal: |
12 | | - |
13 | | -```text |
14 | | -npm install dnotebook |
15 | | -``` |
16 | | - |
17 | | -## Running Dnotebook |
18 | | - |
19 | | -Also, in your open terminal, you can run the command: |
20 | | - |
21 | | -```text |
22 | | -dnotebook |
23 | | -``` |
24 | | - |
25 | | -which will open a new tab in your default web browser pointing to http://localhost:4400. It should look like the screenshot below: |
26 | | - |
27 | | - |
28 | | - |
29 | | -This page is the default notebook interface. From here you can start writing JavaScript or Markdown. |
30 | | - |
31 | | -## Cells |
32 | | - |
33 | | -Cells form the body of a notebook. In the screenshot above, the dark cell is an empty cell. There are two types of cell namely: |
34 | | - |
35 | | -* **Code cell:** These cells ****contain JavaScript code to be executed and the output is displayed below. |
36 | | -* **Markdown cell:** These ****contain text formatted using Markdown. |
37 | | - |
38 | | -### Code Cell |
39 | | - |
40 | | -The first cell in a new notebook is always a code cell. Any JavaScript code can be written and executed in a code cell. Let’s test this out with the classic hello world example. Type `console.log('Hello World!')` into the code cell and click the run button. |
41 | | - |
42 | | -{% hint style="info" %} |
43 | | -Hovering over the code cell reveals the **run** button. Alternatively, you can use the shortcut **Ctrl + Enter** \(Win\)/ **Command + Enter** \(Mac\) to run the code cell. |
44 | | -{% endhint %} |
45 | | - |
46 | | -The result should look like this: |
47 | | - |
48 | | - |
49 | | - |
50 | | -### Markdown |
51 | | - |
52 | | -[Markdown](https://www.markdownguide.org/) is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Markdown is written in Text cells. To create a text cell, hover over any cell and click the **Text** button. You can choose to add a markdown cell above or below the current cell. |
53 | | - |
54 | | - |
55 | | - |
56 | | -In the Text box, you can add any markdown text. For example, copy and paste the text below into the markdown text box. |
57 | | - |
58 | | -```text |
59 | | -# This is a level 1 heading |
60 | | -## This is a level 2 heading |
61 | | -
|
62 | | -This is some plain text that forms a paragraph. |
63 | | -Add emphasis via **bold** and __bold__, or *italic* and _italic_. |
64 | | -Paragraphs must be separated by an empty line. |
65 | | -* Sometimes we want to include lists. |
66 | | -* Which can be indented. |
67 | | -1. Lists can also be numbered. |
68 | | -2. For ordered lists. |
69 | | -[It is possible to include hyperlinks](https://www.example.com) |
70 | | -Inline code uses single backticks: `foo()`, and code blocks use triple backticks: |
71 | | -
|
72 | | -``` |
73 | | -bar() |
74 | | -``` |
75 | | -Or can be indented by 4 spaces: |
76 | | - foo() |
77 | | -And finally, adding images is easy:  |
78 | | -``` |
79 | | - |
80 | | - |
81 | | - |
82 | | -To run a markdown cell, you can double click on it, or use the run button. This renders the output in-place of the markdown text. |
83 | | - |
84 | | - |
85 | | - |
86 | | -{% hint style="info" %} |
87 | | -To re-edit a markdown cell, you can double click it again. |
88 | | -{% endhint %} |
89 | | - |
90 | | -## Persistence/State |
91 | | - |
92 | | -Each instance of a notebook runs a persistent state, and variables declared in any cell is available to all cells. |
93 | | - |
94 | | -For example, if you load packages or declare variables in one cell, they will be available in another. In this way, you can think of a notebook document as being somewhat comparable to a script file, except that it is multimedia. Let’s try this out to get a feel for it. First, we’ll load danfo.js and tensorflow.js packages, and then create a simple model. |
95 | | - |
96 | | -```javascript |
97 | | -//load package downloads and install any JavaScript package via its CDN |
98 | | - |
99 | | -load_package(["https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@latest", |
100 | | - "https://cdn.jsdelivr.net/npm/danfojs@0.1.1/dist/index.min.js"]) |
101 | | -``` |
102 | | - |
103 | | -{% hint style="info" %} |
104 | | -**load\_package** is a built in method to help you load libraries/packages into your notebook via their CDN links. It can accept an array of links. |
105 | | -{% endhint %} |
106 | | - |
107 | | -Once we’ve executed the cell above, we can reference **tf** \(Tensorflow.js\) and **dfd** \(Danfo.js\) in any other cell. For example, we can create a Danfo DataFrame from the code below: |
108 | | - |
109 | | -```text |
110 | | - json_data = [{ A: 0.4612, B: 4.28283, C: -1.509, D: -1.1352 }, |
111 | | - { A: 0.5112, B: -0.22863, C: -3.39059, D: 1.1632 }, |
112 | | - { A: 0.6911, B: -0.82863, C: -1.5059, D: 2.1352 }, |
113 | | - { A: 0.4692, B: -1.28863, C: 4.5059, D: 4.1632 }] |
114 | | -
|
115 | | -df = new dfd.DataFrame(json_data) |
116 | | -table(df) |
117 | | -``` |
118 | | - |
119 | | - |
120 | | - |
121 | | -{% hint style="info" %} |
122 | | -To display Danfo Objects \(DataFrame/Series\), use the inbuilt **table** function by passing the object you want to display. If you the normal **print**\(\) statement, the result gets printed to the browser console |
123 | | -{% endhint %} |
124 | | - |
125 | | -Add a new code cell and create some simple tensors as shown below: |
126 | | - |
127 | | -```javascript |
128 | | -var xs = tf.tensor2d([[0,0],[0,1],[1,0],[1,1]]) |
129 | | -var ys = tf.tensor2d([[0],[1],[1],[0]]) |
130 | | - |
131 | | -function getModel(){ |
132 | | - var model = tf.sequential() |
133 | | - model.add(tf.layers.dense({units:8, inputShape:2, activation: 'tanh'})) |
134 | | - model.add(tf.layers.dense({units:1, activation: 'sigmoid'})) |
135 | | - model.compile({optimizer: 'sgd', loss: 'binaryCrossentropy', lr:0.1}) |
136 | | - return model |
137 | | -} |
138 | | -``` |
139 | | - |
140 | | - |
141 | | - |
142 | | -You can print out any object using the **console.log** function. This will print object both in the browser console and also in the output div below the cell. |
143 | | - |
144 | | -```javascript |
145 | | -console.log(xs) |
146 | | -``` |
147 | | - |
148 | | -{% hint style="info" %} |
149 | | -To open the browser console use **Option + ⌘ + J** \(on macOS\), or **Shift + CTRL + J** \(on Windows/Linux\). It is encouraged to open the console when experimenting as error messages are properly formatted in the console. |
150 | | -{% endhint %} |
151 | | - |
152 | | - |
153 | | - |
154 | | - |
155 | | - |
156 | | -In a new cell below, you can create and train a simple model: |
157 | | - |
158 | | -```javascript |
159 | | -var loss = [] |
160 | | -var epochs = [] |
161 | | -const model = getModel() |
162 | | - |
163 | | -model.fit(xs, ys, { |
164 | | - batchSize: 1, |
165 | | - epochs: 50, |
166 | | - callbacks: { |
167 | | - onEpochEnd: async(epoch, logs)=>{epochs.push(epoch); loss.push((logs.loss).toFixed(4))} |
168 | | - } |
169 | | -}) |
170 | | -``` |
171 | | - |
172 | | -We save the loss after each epoch so we can plot it using Danfo.js inbuilt plotting method. |
173 | | - |
174 | | -```javascript |
175 | | -s = new dfd.Series(loss) |
176 | | -s.plot(this_div()).line() |
177 | | -``` |
178 | | - |
179 | | -{% hint style="info" %} |
180 | | -To plot using Danfo.js, you need to specify a div name. You can access the output div below each code cell by calling the function **this\_div\( \)** |
181 | | -{% endhint %} |
182 | | - |
183 | | - |
184 | | - |
185 | | -## File options |
186 | | - |
187 | | -Clicking on the options tab reveals a couple of file options for you notebook: |
188 | | - |
189 | | - |
190 | | - |
191 | | -You can rename, download and also upload a notebook. |
192 | | - |
193 | | -### Renaming Your Notebooks |
194 | | - |
195 | | -Clicking the rename option opens a modal where you can input the name. Once you're done, click the close button. |
196 | | - |
197 | | - |
198 | | - |
199 | | -### Downloading Your Notebooks |
200 | | - |
201 | | -You can download a notebook for later use. The download button saves the notebook as a JSON object that can be re-uploaded to Dnotebooks. For instance, you'll download this example notebook you've created and re-upload below: |
202 | | - |
203 | | - |
204 | | - |
205 | | -### Importing Saved Notebooks |
206 | | - |
207 | | -You can upload the saved notebook from the example above. First, refresh the page, and in the new instance, click the **option** and then **upload.** |
208 | | - |
209 | | - |
210 | | - |
211 | | -Select the file you download earlier \(myNotebook.json\). This will automatically load and display the file: |
212 | | - |
213 | | - |
214 | | - |
215 | | -You can also interact and run the notebook as you'd do with any other notebook. |
216 | | - |
217 | | -## Extra Functions |
218 | | - |
219 | | -### load\_package\(\) |
220 | | - |
221 | | -The load package method helps you to easily add external packages/libraries to your notebook via their CDN links. For instance, to load Tensorflow.js and Plotly.js, you can do the following: |
222 | | - |
223 | | -```javascript |
224 | | -load_package(["https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@latest", |
225 | | - "https://cdn.plot.ly/plotly-latest.min.js"]) |
226 | | -``` |
227 | | - |
228 | | -After loading the packages, you can access them as you would normally do in an HTML page. For instance, you can plot interactive graphs as shown below: |
229 | | - |
230 | | -```javascript |
231 | | -var trace1 = { |
232 | | - x: [1, 2, 3, 4], |
233 | | - y: [10, 11, 12, 13], |
234 | | - mode: 'markers', |
235 | | - marker: { |
236 | | - size: [40, 60, 80, 100] |
237 | | - } |
238 | | -}; |
239 | | - |
240 | | -var data = [trace1]; |
241 | | - |
242 | | -var layout = { |
243 | | - title: 'Marker Size', |
244 | | - showlegend: false, |
245 | | - height: 600, |
246 | | - width: 600 |
247 | | -}; |
248 | | - |
249 | | -Plotly.newPlot(this_div(), data, layout); //this_div is a function that returns the current output div name |
250 | | -``` |
251 | | - |
252 | | - |
253 | | - |
254 | | -### load\_csv\(\) |
255 | | - |
256 | | -The **load\_csv** function helps you load CSV files over the internet into Danfo.js DataFrame asynchronously. You should use this instead of Danfo.js built-in **read\_csv** function when reading big files and you want to track the progress. load\_csv displays a spinner on the navbar to indicate the state of the load method. |
257 | | - |
258 | | -Add the following line of code to a code cell, and run it. |
259 | | - |
260 | | -```javascript |
261 | | -var df |
262 | | -load_csv("https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv") |
263 | | -.then((d)=>{ |
264 | | - df = d |
265 | | -}) |
266 | | -``` |
267 | | - |
268 | | -If you observe the top right corner, you'll notice a spinner that indicates the state of the cell. |
269 | | - |
270 | | - |
271 | | - |
272 | | -### table\(\) |
273 | | - |
274 | | -To easily display Danfo.js DataFrame/series you can use the built-in **table** function. Just call it from any cell and pass in the DataFrame object. For instance, after loading the finance dataset above, you can display it as shown below: |
275 | | - |
276 | | -```javascript |
277 | | -table(df) //displays object as a formated table |
278 | | -``` |
279 | | - |
280 | | - |
281 | | - |
282 | | -### this\_div\(\) |
283 | | - |
284 | | -The function **this\_div**\(\) will return the id of the current code cell's output. This can be used when plotting, or when you want to display content in the output cell. |
285 | | - |
286 | | -See the example below which plots two columns in the finance DataFrame against a Date index. |
287 | | - |
288 | | -```javascript |
289 | | -var layout = { |
290 | | - title: 'A financial charts', |
291 | | - xaxis: { |
292 | | - title: 'Date', |
293 | | - }, |
294 | | - yaxis: { |
295 | | - title: 'Count', |
296 | | - } |
297 | | -} |
298 | | - |
299 | | -new_df = df.set_index({ key: "Date" }) |
300 | | -new_df.plot(this_div()).line({ columns: ["AAPL.Open", "AAPL.High"], layout: layout }) |
301 | | - |
302 | | -``` |
303 | | - |
304 | | - |
305 | | - |
306 | | -### forlog\(\) |
307 | | - |
308 | | -When looping, **console.log\(\)** will only display the last element of the loop in the output cell: |
309 | | - |
310 | | -```javascript |
311 | | -for(let i=0; i<10; i++){ |
312 | | - console.log(i) |
313 | | -} |
314 | | -``` |
315 | | - |
316 | | - |
317 | | - |
318 | | -To view all elements of a loop in the output cell, you can use a custom **forlog** method as shown below: |
319 | | - |
320 | | -```javascript |
321 | | -for(let i=0; i<10; i++){ |
322 | | - console.forlog(i) |
323 | | -} |
324 | | -``` |
325 | | - |
326 | | - |
327 | | - |
328 | | -## Extra Links: |
329 | | - |
330 | | -* Play with the getting started notebook here. |
| 3 | +Danfo Notebook \(Dnotebook\) is an open-source project, born out of the need to perform quick and interactive experimentation/prototyping with [Danfo.js](https://danfo.jsdata.org/). Dnotebook is a similar to the popular [Jupyter Notebook](https://jupyter.org/) but is customized for the JavaScript environment. Dnotebook is part of our grand vision at [JSdata](https://github.com/opensource9ja) to bring more Data Science and Machine Learning tools to the JavaScript ecosystem. |
331 | 4 |
|
| 5 | +## What can it be used for? |
332 | 6 |
|
| 7 | +Dnotebook allows you to create and share pages that contain live code, text and visualizations in a textbook-like manner. |
333 | 8 |
|
| 9 | +### **Data Science/Analysis** |
334 | 10 |
|
| 11 | +Easily perform interactive data exploration and analysis using efficient JavaScript packages like Danfo.js. |
335 | 12 |
|
| 13 | +### **Machine Learning** |
336 | 14 |
|
| 15 | +Easily build, train and prototype machine learning models using different tools like Tensorflow.js |
337 | 16 |
|
| 17 | +### **Learning JavaScript Interactively** |
338 | 18 |
|
| 19 | +Learn/teach JavaScript in an interactive/visual style. This can hasten learning and understanding. |
339 | 20 |
|
| 21 | +### **Plain Experimentation/Prototype** |
340 | 22 |
|
| 23 | +Any experimentation performed in JavaScript can run on Dnotebooks. |
341 | 24 |
|
| 25 | +## Creators and Core Maintainers |
342 | 26 |
|
| 27 | +Dnotebooks was created by [Rising Odegua](https://twitter.com/risingodegua) and [Stephen Oni](https://twitter.com/steveoni). It is actively maintained by them as well. If you're looking to contribute to making it better, you can raise issues here. Dnotebook is hosted on [GitHub](https://github.com/opensource9ja/notebookjs). |
343 | 28 |
|
0 commit comments