# Notebooks ## What is a notebook? 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. ## What kinds of cell are there? 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](/docs/notebooks/cells) for each kind, [Libraries](/docs/notebooks/libraries) for what a Python cell can import, and [Running](/docs/notebooks/running) for how a run works and what it keeps. ## How do several people edit at once? 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. ## Who can read and run a notebook? 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](/docs/notebooks/parameters)). See [How sharing works](/docs/sharing/overview). 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**. ## How do you import a Jupyter file? **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. ## What is a notebook's context? 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. ## What can your agent do with a notebook? 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](/docs/mcp-tools/notebooks). `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.