# Cells

## How do you add and arrange cells?

A notebook is one markdown document. The buttons under the last cell add its three kinds of cell:
**Text**, **Python** and **Data**, and a + between two cells adds one there. A cell's ⋯ menu moves it
up or down, copies, duplicates or deletes it, and runs every cell from the top down to it. The kind
name at the top of a cell, such as PYTHON, changes it to another kind. Text and Python keep the words.

## What is a text cell for?

A text cell is markdown and renders as part of the document. Use it for the question, what the
numbers mean, and the conclusion, so the notebook reads as an analysis rather than a script. Headings,
lists, links and tables all render. A text cell never runs and has no output.

## What does a Python cell do?

A Python cell reads your workspace data through the `vistazo` library and analyses it.

````
```python
import statsmodels.formula.api as smf
sales = await vistazo.widget('w_8f2c1d')
result = smf.ols('margin ~ units + C(region)', data=sales).fit().summary2().tables[1]
```
````

A cell shows the value of its last line, as in Jupyter. End on a DataFrame for a table, leave a
matplotlib figure open for a chart, or print for text. Assigning `result` also sets what the cell
shows. A trailing semicolon hides the last line's value.

A cell keeps one output, so a cell that draws a chart and then ends on a table keeps only the table.
An error's traceback is recorded against the cell that raised it. Variables carry between cells, which
can run in any order.

## How does a data cell pull a table?

A data cell pulls one table without any code. Pick a **Connection**, then one of its read-only tools,
and fill in the arguments it asks for. To read an uploaded file instead, pick **Uploads** as the
connection and choose the file.

The form shows the arguments a tool requires. **Add**, beside the Arguments heading, lists the rest.
Type to narrow the list and pick one to add it. The × beside an added argument removes it, so the
tool's default applies. Tap ⓘ beside the connection, the tool or an argument to read what it means.

Set the **Variable**, which is `df` unless you change it, and run the cell. The table shows under the
cell, and that name is a DataFrame in every Python cell below.

A data cell runs as exactly one `vistazo.call` or `vistazo.dataset` line. Pick **Python** from its kind
name to turn it into that line and edit the code. Picking **Data** turns that one line back into the
form, and turns an empty cell into a data cell. Python that does anything more stays Python. Reading a
widget's rows has no form, so that stays a Python line.

The spark beside a cell's Run button hands the cell to the notebook's assistant panel. On a data cell
it fills in the form for you.