Execution

Stencila documents can contain executable code as part of the document itself. This makes it possible to combine narrative writing with analysis, computation, generated outputs, and reusable executable document components.

Tip

If you only want to show code without running it, see Code.

Executable code chunks

Add the exec flag to a fenced code block to make it executable:

```python exec
# Some python code
a = 3
```

When Stencila executes a code chunk, it runs the code using an appropriate kernel for the language and attaches any resulting outputs to the document. Those outputs can include text, tables, figures, and other rendered results.

You can also omit the language:

```exec
No language
```

Execution modes

Execution modes can be added after exec:

```js exec always
// Javascript
```

Execution modes control when or whether a chunk runs. For example, always indicates that the chunk should be rerun whenever execution is performed, while modes such as lock are useful when you want to preserve existing outputs instead of recomputing them automatically.

Inline code expressions

Inline code expressions let you embed computed values directly in prose:

With a number output `6 * 7`{python exec}.

With a number output 42.

These are useful for values that should stay synchronized with your analysis, such as counts, parameter values, summary statistics, or short derived strings that appear inside narrative text.

With a string output `'a string'`{python exec}.

With a string output a string.

With an array output `[1, 2, 3]`{python exec}.

With an array output 123.

With an object output `dict(a=1,b=dict())`{python exec}.

With an object output 1.

You can also omit the language or specify an execution mode:

With no language specified and no output `a + b`{exec}.

With no language specified and no output null.

With execution mode specified and no output `c * d`{javascript exec lock}.

With execution mode specified and no output .

Labelled chunks

Executable chunks can be wrapped in a labelled chunk block:


::: chunk 1A

```exec
# Chunk 1A
```

:::

Executable figures and tables

Executable code can also be wrapped in figures and tables so that outputs have captions and labels:


::: figure 1

```r exec
plot(y~x)
```
Y against X.

:::

Figure 1: Y against X.


::: table 1

```r exec
head(mtcars)
```
Some cars.

:::

Table 1: Some cars.

name	mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
Mazda RX4	21	6	160	110	3.9	2.62	16.46	0	1	4	4
Mazda RX4 Wag	21	6	160	110	3.9	2.875	17.02	0	1	4	4
Datsun 710	22.8	4	108	93	3.85	2.32	18.61	1	1	4	1
Hornet 4 Drive	21.4	6	258	110	3.08	3.215	19.44	1	0	3	1
Hornet Sportabout	18.7	8	360	175	3.15	3.44	17.02	0	0	3	2
Valiant	18.1	6	225	105	2.76	3.46	20.22	1	0	3	1

Parameters

Parameters define values that can be supplied to executable documents:

A boolean parameter &[par_bool_1]{bool}, with a default &[par_bool_2]{bool def=true}, with a default and value &[par_bool_3]{bool def=false}

A boolean parameter , with a default , with a default and value

Parameters are especially useful when a document is intended to be reused with different inputs. Other documents can then provide those values using Includes and calls, allowing one executable document to act like a reusable, parameterized component.

Tip

For includes and document calls, see Includes and calls.

Tip

If you ended up here but only need static code examples, language-tagged code fragments, or ordinary fenced code blocks, see Code.

For related authoring features, see: