Notebooks

A notebook is a written analysis with Python in it. Prose sets out the question, and Python cells pull rows from your workspace and do the statistics. Use one for the work a chart can't do, such as a regression, a seasonal decomposition, a t-test or a clustering.

Notebooks are under Notebooks in the nav.

A new workspace starts with an example, [demo] Tornado Fatalities. It asks whether a tornado that strikes at night is deadlier than one of the same strength by day. It answers with a logistic regression on NOAA storm records for ten Southeast states. It reads data both ways a notebook can, with a data cell for one fixed fetch and vistazo.call in Python for the calls its code works out. Its tables and chart are stored when the workspace is made, so reading it uses no compute. Run it to watch the cells work, then edit, copy or archive it like any other notebook.

A notebook is one markdown document. The buttons under the last cell add its three kinds of cell: Text, Python and Data. Text is markdown and renders as part of the document. A Python cell reads your workspace data through the vistazo library and analyses it, and a data cell pulls one table without any code. See Cells for each kind, Libraries for what a Python cell can import, and Running for how a run works and what it keeps.

Several people can edit a notebook at once, and each sees the others' changes as they type. The header shows who has it open, and a face beside a cell shows whose caret is in it. Only the cells are shared. Each person runs their own kernel, with their own variables.

When the built-in assistant writes cells, you watch them arrive. Each appears as it is written, marked Writing, and becomes an ordinary cell when the write lands. Anyone else with the notebook open sees the same, labelled with whose assistant it is.

An edit from the built-in assistant or your agent is merged into the notebook as people have it open. Anything people typed after the assistant or your agent read the notebook is kept. If the edit would rewrite text someone changed since, it is refused rather than deleting theirs. The assistant or your agent is then told who is editing the cell, when that person has their caret in it.

Notebooks share like dashboards and skills. Open Settings → Sharing on the notebook to name people or change the workspace baseline. An editor can change and run the notebook, and a viewer reads it. A notebook with parameters also lets a viewer run it with their own values, saving nothing (Parameters). See How sharing works.

Turn on public access and anyone with the notebook's address can read it. The public view shows the prose, the cells and the outputs of the last run, figures and large tables included. A large table shows its first 100 rows. A data cell shows as its form, read-only, with each argument listed by name. Nothing on the public view runs.

A notebook nobody has edited, opened, run or read through its public view for 90 days is archived, and it moves behind the archived control at the foot of the notebooks list. The demo notebook Vistazo added to the workspace is never archived this way. It opens frozen with its last outputs and can't be edited or run until someone with edit access presses Restore.

Import .ipynb on the notebooks list turns a Jupyter file into a Vistazo notebook. Markdown cells stay markdown, and code cells become Python cells. Three things change on the way in.

• Stored outputs are dropped, because a run here reproduces them.
• Magics and shell lines, such as %matplotlib and !pip install, are commented out, because there is no shell and no installer.
• A cell that reads a file or the network, or imports a package that isn't installed, is flagged in a note at the top. Upload the file and read it with await vistazo.dataset('name'), or fetch the rows from a connected source with vistazo.call.

Download in a notebook's ⋯ menu saves a .ipynb file with the last run's outputs and figures. Each data cell is written as the Python line it runs. Importing that file again brings the cells back as Python cells, without the outputs.

Every notebook carries a written summary of itself. It holds a short description, the audience, the key uses, caveats, and a plain-language reading of each Python and data cell. Vistazo rewrites it a few minutes after the notebook changes. A cell you have edited since then has no reading until the next rewrite.

The built-in assistant reads this summary in the notebook's panel, so it can tell which cells matter before it reads them. Your agent gets it from get_notebook. Read it under Settings → Context. A workspace admin can also regenerate it there.

Your agent can create and edit notebooks with save_notebook, read one with get_notebook, find them with list_notebooks, and run one with run_notebook. save_notebook with ops edits single cells, and with ipynb it imports a Jupyter file. set_parameter with the notebook's id defines its parameters. The built-in assistant has all of these except the import. Both read a run's outputs, trimmed, through get_notebook and run_notebook. See Notebook tools.

run_notebook restarts the kernel and runs every cell with the parameter defaults. It runs under the access of the person who asked the built-in assistant, or whose account your agent signed in with. It runs every cell as written, including cells the assistant or your agent just added, with no review step. The built-in assistant asks on a confirmation card before it rewrites or deletes existing cells, and never before a run.