Parameters

A parameter is a named input that a notebook's cells read, such as a country, a date window or a threshold. It works like a dashboard filter. Each parameter has a default, and the defaults are what everyone sees when they open the notebook. Schedules, run_notebook and the public view always run with the defaults.

Anyone who can open the notebook, other than a guest, can try their own values in the Parameters tab. Those runs are yours alone, and nothing about them is saved.

Ask the built-in assistant in the notebook's panel, or your agent, to add one:

Add a country parameter with the G7 countries, defaulting to the US, and make the cells read it.

It calls set_parameter with the notebook's id. Adding, changing a default and removing a parameter all take Editor on the notebook. There is no form for it in the notebook itself.

• A parameter has a key, a label, a type and a default. The types are a dashboard parameter's (types).
• The key is what cells use. It holds letters, digits and underscores, and doesn't start with a digit, so country or min_rate.
• A select or multi_select takes a fixed list of options, up to 500, or 200 for a multi_select. A notebook parameter can't fetch its options from a data source.
• A date default can be relative, such as today-30, so it moves with the calendar (relative dates).
• Changing a default runs nothing. The outputs stay as they last ran until the next run or schedule.

When you remove a parameter, the reply names the cells that read it. Those cells fail when they next run, until you add it back or change them.

Each kind of cell reads it its own way, and none of them pastes the value into your code.

• Python calls vistazo.param('country'), without await. It returns the value in its own type, a list for a multi-select and a start and end for a date range. Asking for a key the notebook doesn't define raises an error that lists the keys it does.
• Data writes {{ params.country }} in an argument. A hole can be the whole argument or part of longer text, such as Sales in {{ params.country }}. {{ dates.today-30 }} fills in a date the same way.
• Text writes {{ params.country }} in prose, and the page shows the value there. A pick list shows its option's label. The value always reads as plain text, never as a link or formatting.

A text cell shows the values the last run used, or the defaults when nothing has run. While you edit the text, the holes stay as you wrote them.

Open the Parameters tab in the notebook's side panel, beside the built-in assistant. On a phone it is in the bar at the bottom. The tab appears once the notebook has a parameter.

1. Change one or more values. The revert button beside a row puts its default back.
2. Press Apply. The notebook runs with your values, and Stop halts it.
3. Read the results. The page says Showing your values while they are on screen.
4. Press Reset to go back to the published run.

The first Apply runs every cell. A later one runs again from the first cell your change affects, and keeps the cells above it. Hovering over an output shows the values it ran with. A cell whose output came from other values than the ones in effect is marked outdated.

A link to the notebook can carry values of its own. Opening it fills in the form, and nothing runs until you press Apply, since a run uses your compute.

It runs in your own kernel, with your own connections. When a data cell reads a source you haven't connected, the page asks you to connect it before anything runs. A run never borrows anyone else's connection. It uses your compute, as any run does (Usage).

Nothing about it is saved. Nobody else sees your values or their outputs, and neither do the built-in assistant, your agent or the public view. Reloading the page shows the published run again. Your saved variables from your own runs of the notebook are kept, and come back after Reset.

A viewer runs the notebook only through Apply, and can't run single cells or change the code. An editor who presses Run on a cell while their values are showing runs it with those values. Guests and people reading the public view see the published run, with no Parameters tab.

• Duplicate copies a notebook's parameters along with its cells.
• A Jupyter file carries no parameters either way. Download writes the vistazo.param calls as code. Import .ipynb defines none, and the note at the top names each cell that reads one, so you can add them.