From ff90433ecac5b78032be9c5eb266888c47bee8c1 Mon Sep 17 00:00:00 2001 From: Winston Chang Date: Thu, 14 Mar 2024 16:13:57 -0500 Subject: [PATCH 1/2] Switch imports from shiny to shiny.express --- .../execute-results/html.json | 2 +- docs/dashboards/_examples/app.py | 5 +- docs/dashboards/_examples/inputs/app.py | 52 ++++++++++++++----- .../_examples/inputs/card-toolbar.qmd | 2 +- .../_examples/inputs/column-layout.qmd | 3 +- .../_examples/inputs/inline-sidebar.qmd | 2 +- .../_examples/inputs/inline-toolbar.qmd | 6 +-- .../_examples/inputs/input-panel.qmd | 2 +- .../_examples/inputs/page-sidebar.qmd | 2 +- .../_examples/inputs/right-sidebar.qmd | 3 +- docs/dashboards/_examples/inputs/toolbar.qmd | 2 +- .../_examples/shiny-global-sidebar.qmd | 3 +- .../_examples/shiny-python-simple.qmd | 2 +- docs/dashboards/_examples/shiny-sidebar.qmd | 3 +- docs/dashboards/_inputs.qmd | 20 +++---- docs/dashboards/data-display.qmd | 2 +- .../shiny-python/_shiny-advanced.md | 3 +- .../shiny-python/_shiny-sidebar.md | 2 +- .../interactivity/shiny-python/index.qmd | 3 +- 19 files changed, 78 insertions(+), 41 deletions(-) diff --git a/_freeze/docs/computations/execution-options/execute-results/html.json b/_freeze/docs/computations/execution-options/execute-results/html.json index 4404df286c..fa874d7a13 100644 --- a/_freeze/docs/computations/execution-options/execute-results/html.json +++ b/_freeze/docs/computations/execution-options/execute-results/html.json @@ -2,7 +2,7 @@ "hash": "307951cb3cfda279dd5e9a3f361c5b82", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Execution Options\nformat: html\n---\n\n## Output Options\n\nThere are a wide variety of options available for customizing output from executed code. All of these options can be specified either globally (in the document front-matter) or per code-block. For example, here's a modification of the Python example to specify that we don't want to \"echo\" the code into the output document:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\nOptions available for customizing output include:\n\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+===========+===================================================================================================================================================================================================+\n| `eval` | Evaluate the code chunk (if `false`, just echos the code into the output). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `echo` | Include the source code in output |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `output` | Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto's standard enclosing markdown). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `warning` | Include warnings in the output. |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `error` | Include errors in the output (note that this implies that errors executing code will not halt processing of the document). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nHere's a Knitr example with some of these additional options included:\n\n```` \n---\ntitle: \"Knitr Document\"\nexecute:\n echo: false\n---\n\n```{{r}}\n#| warning: false\n\nlibrary(ggplot2)\nggplot(airquality, aes(Temp, Ozone)) + \n geom_point() + \n geom_smooth(method = \"loess\", se = FALSE)\n```\n\n```{{r}}\nsummary(airquality)\n```\n````\n\n::: callout-tip\nWhen using the Knitr engine, you can also use any of the available native options (e.g. `collapse`, `tidy`, `comment`, etc.). See the [Knitr options documentation](https://yihui.org/knitr/options/) for additional details. You can include these native options in option comment blocks as shown above, or on the same line as the `{r}` as shown in the Knitr documentation.\n:::\n\n::: callout-tip\nThe Knitr engine can also *conditionally* evaluate a code chunk using objects or expressions. See [Using R: Knitr Options](r.qmd#chunk-options).\n:::\n\n## Figure Options\n\nThere are a number of ways to control the default width and height of figures generated from code. First, it's important to know that Quarto sets a default width and height for figures appropriate to the target output format. Here are the defaults (expressed in inches):\n\n| Format | Default |\n|-------------------------|-----------|\n| Default | 7 x 5 |\n| HTML Slides | 9.5 x 6.5 |\n| HTML Slides (reveal.js) | 9 x 5 |\n| PDF | 5.5 x 3.5 |\n| PDF Slides (Beamer) | 10 x 7 |\n| PowerPoint | 7.5 x 5.5 |\n| MS Word, ODT, RTF | 5 x 4 |\n| EPUB | 5 x 4 |\n| Hugo | 8 x 5 |\n\nThese defaults were chosen to provide attractive well proportioned figures, but feel free to experiment to see whether you prefer another default size. You can change the default sizes using the `fig-width` and `fig-height` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html:\n fig-width: 8\n fig-height: 6\n pdf:\n fig-width: 7\n fig-height: 5\n---\n```\n\nHow do these sizes make their way into the engine-level defaults for generating figures? This differs by engine:\n\n- For the Knitr engine, these values become the default values for the `fig.width` and `fig.height` chunk options. You can override these default values via chunk level options.\n\n- For Python, these values are used to set the [Matplotlib](https://matplotlib.org/stable/tutorials/introductory/customizing.html) `figure.figsize` rcParam (you can of course manually override these defaults for any given plot).\n\n- For Julia, these values are used to initialize the default figure size for the [Plots.jl](https://docs.juliaplots.org/stable/) GR backend.\n\n If you are using another graphics library with Jupyter and want to utilize these values, you can read them from `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` environment variables.\n\n::: callout-caution\nWhen using the Knitr engine, `fig-width` and `fig-height` are supported on a per-cell basis. But when using the Jupyter engine, these options only have an effect if specified at the document- or project-level metadata.\n:::\n\n### Caption and Alt Text\n\nYou can specify the caption and alt text for figures generated from code using the `fig-cap` and `fig-alt` options. For example, here we add these options to a Python code cell that creates a plot:\n\n```{{python}}\n#| fig-cap: \"Polar axis plot\"\n#| fig-alt: \"A line plot on a polar axis\"\n\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nr = np.arange(0, 2, 0.01)\ntheta = 2 * np.pi * r\nfig, ax = plt.subplots(subplot_kw={'projection': 'polar'})\nax.plot(theta, r)\nax.set_rticks([0.5, 1, 1.5, 2])\nax.grid(True)\nplt.show()\n```\n\n## Inline Code\n\nJupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). See [Inline Code](inline-code.qmd) for details.\n\n## Raw Output\n\nThe `output: asis` option enables you to generate raw markdown output. When `output: asis` is specified none of Quarto's standard enclosing divs will be included. For example, here we specify `output: asis` in order to generate a pair of headings:\n\n::: panel-tabset\n## Jupyter\n\n```{{python}}\n#| echo: false\n#| output: asis\n\nprint(\"# Heading 1\\n\")\nprint(\"## Heading 2\\n\")\n```\n\n## Knitr\n\n```{{r}}\n#| echo: false\n#| output: asis\n\ncat(\"# Heading 1\\n\")\ncat(\"## Heading 2\\n\")\n```\n:::\n\nWhich generates the following output:\n\n``` default\n# Heading 1\n\n## Heading 2\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\nIf we had not specified `output: asis` the output, as seen in the intermediate markdown, would have included Quarto's `.cell-output` div:\n\n```` default\n::: {.cell-output-stdout}\n```\n# Heading 1\n\n## Heading 2\n \n```\n:::\n````\n\nFor the Jupyter engine, you can also create raw markdown output using the functions in `IPython.display`. For example:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\n\n## Knitr Options\n\nIf you are using the Knitr cell execution engine, you can specify default document-level [Knitr chunk options](https://yihui.org/knitr/options/) in YAML. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nknitr:\n opts_chunk: \n collapse: true\n comment: \"#>\" \n R.options:\n knitr.graphics.auto_pdf: true\n---\n```\n\nYou can additionally specify global Knitr options using `opts_knit`.\n\nThe `R.options` chunk option is a convenient way to define R options that are set temporarily via [`options()`](https://rdrr.io/r/base/options.html) before the code chunk execution, and immediately restored afterwards.\n\nIn the example above, we establish default Knitr chunk options for a single document. You can also add shared `knitr` options to a project-wide `_quarto.yml` file or a project-directory scoped `_metadata.yml` file.\n\n\n\n## Jupyter Options\n\n### Expression Printing\n\nWhen multiple expressions are present in a code cell, by default, only the last top-level expression is captured in the rendered output. For example, consider the code cell:\n\n::: {layout-ncol=\"2\"}\n```` markdown\n```{{python}}\n\"first\"\n\"last\"\n```\n````\n:::\n\nWhen rendered to HTML the output generated is:\n\n``` markdown\n'last'\n```\n\nThis behavior corresponds to the `last_expr` setting for [Jupyter shell interactivity](https://ipython.readthedocs.io/en/stable/config/options/terminal.html#configtrait-InteractiveShell.ast_node_interactivity).\n\nYou can control this behavior with the `ipynb-shell-interactivity` option. For example, to capture all top-level expressions set it to `all`:\n\n``` yaml\n---\ntitle: All expressions\nformat: html\nipynb-shell-interactivity: all\n---\n```\n\nNow the above code cell results in the output:\n\n``` markdown\n'first'\n\n'last'\n```\n\n::: callout-note\n## All Expressions are Printed in Dashboards\n\nFor [dashboards](/docs/dashboards/) the default setting of `ipynb-shell-interactivity` is `all.`\n:::\n\n## Intermediates\n\nOn the way from markdown input to final output, there are some intermediate files that are created and automatically deleted at the end of rendering. You can use the following options to keep these intermediate files:\n\n+--------------+------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+================================================================================================+\n| `keep-md` | Keep the markdown file generated by executing code. |\n+--------------+------------------------------------------------------------------------------------------------+\n| `keep-ipynb` | Keep the notebook file generated from executing code (applicable only to markdown input files) |\n+--------------+------------------------------------------------------------------------------------------------+\n\nFor example, here we specify that we want to keep the jupyter intermediate file after rendering:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n keep-ipynb: true\njupyter: python3\n---\n```\n\n## Fenced Echo\n\nIf you are writing a tutorial or documentation on using Quarto code blocks, you'll likely want to include the fenced code delimiter (e.g. ```` ```{python} ````) in your code output to emphasize that executable code requires that delimiter. You can do this using the `echo: fenced` option. For example, the following code block:\n\n```{{python}}\n#| echo: fenced\n1 + 1\n```\n\nWill be rendered as:\n\n::: {#d9b2e5a8 .cell execution_count=1}\n```` { .cell-code}\n```{{python}}\n1 + 1\n```\n\n````\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n2\n```\n:::\n:::\n\n\nThis is especially useful when you want to demonstrate the use of cell options. For example, here we demonstrate the use of the `output` and `code-overflow` options:\n\n```{{python}}\n#| echo: fenced\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\nThis code block appears in the rendered document as:\n\n::: {#521ace61 .cell execution_count=2}\n```` { .cell-code .code-overflow-wrap}\n```{{python}}\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\n````\n:::\n\n\nNote that all YAML options will be included in the fenced code output *except for* `echo: fenced` (as that might be confusing to readers).\n\nThis behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nexecute:\n echo: fenced\n---\n```\n\n#### Unexecuted Blocks\n\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Engine Binding\n\nEarlier we said that the engine used for computations was determined automatically. You may want to customize this---for example you may want to use the Jupyter [R kernel](https://github.com/IRkernel/IRkernel) rather than Knitr, or you may want to use Knitr with Python code (via [reticulate](https://rstudio.github.io/reticulate/)).\n\nHere are the basic rules for automatic binding:\n\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Extension | Engine Binding |\n+===========+========================================================================================================================================================================================================================================+\n| .qmd | Use Knitr engine if an `{r}` code block is discovered within the file |\n| | |\n| | Use Jupyter engine if *any other* executable code block (e.g. `{python}`, `{julia}`, `{bash}`, etc.) is discovered within the file. The kernel used is determined based on the language of the first executable code block discovered. |\n| | |\n| | Use no engine if no executable code blocks are discovered. |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .ipynb | Jupyter engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .Rmd | Knitr engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .md | No engine (note that if an `md` document does contain executable code blocks then an error will occur) |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nFor `.qmd` files in particular, you can override the engine used via the `engine` option. For example:\n\n``` markdown\nengine: jupyter\n```\n\n``` markdown\nengine: knitr\n```\n\nYou can also specify that no execution engine should be used via `engine: markdown`.\n\nThe presence of the `knitr` or `jupyter` option will also override the default engine:\n\n``` markdown\nknitr: true\n```\n\n``` markdown\njupyter: python3\n```\n\nVariations with additional engine-specific options also work to override the default engine:\n\n``` markdown\nknitr:\n opts_knit:\n verbose: true\n```\n\n``` markdown\njupyter:\n kernelspec:\n display_name: Python 3\n language: python\n name: python3\n```\n\n## Shell Commands\n\nUsing shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine. If you are using the Jupyter engine you can use [Jupyter shell magics](https://jakevdp.github.io/PythonDataScienceHandbook/01.05-ipython-and-shell-commands.html). For example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: jupyter\n---\n\n```{{python}}\n!echo \"foo\"\n```\n````\n\nNote that `!` preceding `echo` is what enables a Python cell to be able to execute a shell command.\n\nIf you are using the Knitr engine you can use ```` ```{bash} ```` cells, for example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: knitr\n---\n\n```{{bash}}\necho \"foo\" \n```\n````\n\nNote that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document\n\n", + "markdown": "---\ntitle: Execution Options\nformat: html\n---\n\n## Output Options\n\nThere are a wide variety of options available for customizing output from executed code. All of these options can be specified either globally (in the document front-matter) or per code-block. For example, here's a modification of the Python example to specify that we don't want to \"echo\" the code into the output document:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\nOptions available for customizing output include:\n\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+===========+===================================================================================================================================================================================================+\n| `eval` | Evaluate the code chunk (if `false`, just echos the code into the output). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `echo` | Include the source code in output |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `output` | Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto's standard enclosing markdown). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `warning` | Include warnings in the output. |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `error` | Include errors in the output (note that this implies that errors executing code will not halt processing of the document). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nHere's a Knitr example with some of these additional options included:\n\n```` \n---\ntitle: \"Knitr Document\"\nexecute:\n echo: false\n---\n\n```{{r}}\n#| warning: false\n\nlibrary(ggplot2)\nggplot(airquality, aes(Temp, Ozone)) + \n geom_point() + \n geom_smooth(method = \"loess\", se = FALSE)\n```\n\n```{{r}}\nsummary(airquality)\n```\n````\n\n::: callout-tip\nWhen using the Knitr engine, you can also use any of the available native options (e.g. `collapse`, `tidy`, `comment`, etc.). See the [Knitr options documentation](https://yihui.org/knitr/options/) for additional details. You can include these native options in option comment blocks as shown above, or on the same line as the `{r}` as shown in the Knitr documentation.\n:::\n\n::: callout-tip\nThe Knitr engine can also *conditionally* evaluate a code chunk using objects or expressions. See [Using R: Knitr Options](r.qmd#chunk-options).\n:::\n\n## Figure Options\n\nThere are a number of ways to control the default width and height of figures generated from code. First, it's important to know that Quarto sets a default width and height for figures appropriate to the target output format. Here are the defaults (expressed in inches):\n\n| Format | Default |\n|-------------------------|-----------|\n| Default | 7 x 5 |\n| HTML Slides | 9.5 x 6.5 |\n| HTML Slides (reveal.js) | 9 x 5 |\n| PDF | 5.5 x 3.5 |\n| PDF Slides (Beamer) | 10 x 7 |\n| PowerPoint | 7.5 x 5.5 |\n| MS Word, ODT, RTF | 5 x 4 |\n| EPUB | 5 x 4 |\n| Hugo | 8 x 5 |\n\nThese defaults were chosen to provide attractive well proportioned figures, but feel free to experiment to see whether you prefer another default size. You can change the default sizes using the `fig-width` and `fig-height` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html:\n fig-width: 8\n fig-height: 6\n pdf:\n fig-width: 7\n fig-height: 5\n---\n```\n\nHow do these sizes make their way into the engine-level defaults for generating figures? This differs by engine:\n\n- For the Knitr engine, these values become the default values for the `fig.width` and `fig.height` chunk options. You can override these default values via chunk level options.\n\n- For Python, these values are used to set the [Matplotlib](https://matplotlib.org/stable/tutorials/introductory/customizing.html) `figure.figsize` rcParam (you can of course manually override these defaults for any given plot).\n\n- For Julia, these values are used to initialize the default figure size for the [Plots.jl](https://docs.juliaplots.org/stable/) GR backend.\n\n If you are using another graphics library with Jupyter and want to utilize these values, you can read them from `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` environment variables.\n\n::: callout-caution\nWhen using the Knitr engine, `fig-width` and `fig-height` are supported on a per-cell basis. But when using the Jupyter engine, these options only have an effect if specified at the document- or project-level metadata.\n:::\n\n### Caption and Alt Text\n\nYou can specify the caption and alt text for figures generated from code using the `fig-cap` and `fig-alt` options. For example, here we add these options to a Python code cell that creates a plot:\n\n```{{python}}\n#| fig-cap: \"Polar axis plot\"\n#| fig-alt: \"A line plot on a polar axis\"\n\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nr = np.arange(0, 2, 0.01)\ntheta = 2 * np.pi * r\nfig, ax = plt.subplots(subplot_kw={'projection': 'polar'})\nax.plot(theta, r)\nax.set_rticks([0.5, 1, 1.5, 2])\nax.grid(True)\nplt.show()\n```\n\n## Inline Code\n\nJupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). The syntax for this varies across the engines. See [Inline Code](inline-code.qmd) for details.\n\n## Raw Output\n\nThe `output: asis` option enables you to generate raw markdown output. When `output: asis` is specified none of Quarto's standard enclosing divs will be included. For example, here we specify `output: asis` in order to generate a pair of headings:\n\n::: panel-tabset\n## Jupyter\n\n```{{python}}\n#| echo: false\n#| output: asis\n\nprint(\"# Heading 1\\n\")\nprint(\"## Heading 2\\n\")\n```\n\n## Knitr\n\n```{{r}}\n#| echo: false\n#| output: asis\n\ncat(\"# Heading 1\\n\")\ncat(\"## Heading 2\\n\")\n```\n:::\n\nWhich generates the following output:\n\n``` default\n# Heading 1\n\n## Heading 2\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\nIf we had not specified `output: asis` the output, as seen in the intermediate markdown, would have included Quarto's `.cell-output` div:\n\n```` default\n::: {.cell-output-stdout}\n```\n# Heading 1\n\n## Heading 2\n \n```\n:::\n````\n\nFor the Jupyter engine, you can also create raw markdown output using the functions in `IPython.display`. For example:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\n\n## Knitr Options\n\nIf you are using the Knitr cell execution engine, you can specify default document-level [Knitr chunk options](https://yihui.org/knitr/options/) in YAML. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nknitr:\n opts_chunk: \n collapse: true\n comment: \"#>\" \n R.options:\n knitr.graphics.auto_pdf: true\n---\n```\n\nYou can additionally specify global Knitr options using `opts_knit`.\n\nThe `R.options` chunk option is a convenient way to define R options that are set temporarily via [`options()`](https://rdrr.io/r/base/options.html) before the code chunk execution, and immediately restored afterwards.\n\nIn the example above, we establish default Knitr chunk options for a single document. You can also add shared `knitr` options to a project-wide `_quarto.yml` file or a project-directory scoped `_metadata.yml` file.\n\n\n\n## Jupyter Options\n\n### Expression Printing\n\nWhen multiple expressions are present in a code cell, by default, only the last top-level expression is captured in the rendered output. For example, consider the code cell:\n\n::: {layout-ncol=\"2\"}\n```` markdown\n```{{python}}\n\"first\"\n\"last\"\n```\n````\n:::\n\nWhen rendered to HTML the output generated is:\n\n``` markdown\n'last'\n```\n\nThis behavior corresponds to the `last_expr` setting for [Jupyter shell interactivity](https://ipython.readthedocs.io/en/stable/config/options/terminal.html#configtrait-InteractiveShell.ast_node_interactivity).\n\nYou can control this behavior with the `ipynb-shell-interactivity` option. For example, to capture all top-level expressions set it to `all`:\n\n``` yaml\n---\ntitle: All expressions\nformat: html\nipynb-shell-interactivity: all\n---\n```\n\nNow the above code cell results in the output:\n\n``` markdown\n'first'\n\n'last'\n```\n\n::: callout-note\n## All Expressions are Printed in Dashboards\n\nFor [dashboards](/docs/dashboards/) the default setting of `ipynb-shell-interactivity` is `all.`\n:::\n\n## Intermediates\n\nOn the way from markdown input to final output, there are some intermediate files that are created and automatically deleted at the end of rendering. You can use the following options to keep these intermediate files:\n\n+--------------+------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+================================================================================================+\n| `keep-md` | Keep the markdown file generated by executing code. |\n+--------------+------------------------------------------------------------------------------------------------+\n| `keep-ipynb` | Keep the notebook file generated from executing code (applicable only to markdown input files) |\n+--------------+------------------------------------------------------------------------------------------------+\n\nFor example, here we specify that we want to keep the jupyter intermediate file after rendering:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n keep-ipynb: true\njupyter: python3\n---\n```\n\n## Fenced Echo\n\nIf you are writing a tutorial or documentation on using Quarto code blocks, you'll likely want to include the fenced code delimiter (e.g. ```` ```{python} ````) in your code output to emphasize that executable code requires that delimiter. You can do this using the `echo: fenced` option. For example, the following code block:\n\n```{{python}}\n#| echo: fenced\n1 + 1\n```\n\nWill be rendered as:\n\n::: {#c8fc76fc .cell execution_count=1}\n```` { .cell-code}\n```{{python}}\n1 + 1\n```\n\n````\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n2\n```\n:::\n:::\n\n\nThis is especially useful when you want to demonstrate the use of cell options. For example, here we demonstrate the use of the `output` and `code-overflow` options:\n\n```{{python}}\n#| echo: fenced\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\nThis code block appears in the rendered document as:\n\n::: {#c64bcb9e .cell execution_count=2}\n```` { .cell-code .code-overflow-wrap}\n```{{python}}\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\n````\n:::\n\n\nNote that all YAML options will be included in the fenced code output *except for* `echo: fenced` (as that might be confusing to readers).\n\nThis behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nexecute:\n echo: fenced\n---\n```\n\n#### Unexecuted Blocks\n\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Engine Binding\n\nEarlier we said that the engine used for computations was determined automatically. You may want to customize this---for example you may want to use the Jupyter [R kernel](https://github.com/IRkernel/IRkernel) rather than Knitr, or you may want to use Knitr with Python code (via [reticulate](https://rstudio.github.io/reticulate/)).\n\nHere are the basic rules for automatic binding:\n\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Extension | Engine Binding |\n+===========+========================================================================================================================================================================================================================================+\n| .qmd | Use Knitr engine if an `{r}` code block is discovered within the file |\n| | |\n| | Use Jupyter engine if *any other* executable code block (e.g. `{python}`, `{julia}`, `{bash}`, etc.) is discovered within the file. The kernel used is determined based on the language of the first executable code block discovered. |\n| | |\n| | Use no engine if no executable code blocks are discovered. |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .ipynb | Jupyter engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .Rmd | Knitr engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .md | No engine (note that if an `md` document does contain executable code blocks then an error will occur) |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nFor `.qmd` files in particular, you can override the engine used via the `engine` option. For example:\n\n``` markdown\nengine: jupyter\n```\n\n``` markdown\nengine: knitr\n```\n\nYou can also specify that no execution engine should be used via `engine: markdown`.\n\nThe presence of the `knitr` or `jupyter` option will also override the default engine:\n\n``` markdown\nknitr: true\n```\n\n``` markdown\njupyter: python3\n```\n\nVariations with additional engine-specific options also work to override the default engine:\n\n``` markdown\nknitr:\n opts_knit:\n verbose: true\n```\n\n``` markdown\njupyter:\n kernelspec:\n display_name: Python 3\n language: python\n name: python3\n```\n\n## Shell Commands\n\nUsing shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine. If you are using the Jupyter engine you can use [Jupyter shell magics](https://jakevdp.github.io/PythonDataScienceHandbook/01.05-ipython-and-shell-commands.html). For example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: jupyter\n---\n\n```{{python}}\n!echo \"foo\"\n```\n````\n\nNote that `!` preceding `echo` is what enables a Python cell to be able to execute a shell command.\n\nIf you are using the Knitr engine you can use ```` ```{bash} ```` cells, for example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: knitr\n---\n\n```{{bash}}\necho \"foo\" \n```\n````\n\nNote that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document\n\n", "supporting": [ "execution-options_files" ], diff --git a/docs/dashboards/_examples/app.py b/docs/dashboards/_examples/app.py index 6455407d52..9ac8a27b1c 100644 --- a/docs/dashboards/_examples/app.py +++ b/docs/dashboards/_examples/app.py @@ -1,4 +1,5 @@ # This file generated by Quarto; do not edit by hand. +# shiny_mode: core from __future__ import annotations @@ -14,7 +15,7 @@ def server(input: Inputs, output: Outputs, session: Session) -> None: # ======================================================================== - from shiny import render, ui + from shiny.express import render, ui ui.input_select("x", "Variable:", choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) @@ -32,6 +33,8 @@ def displot(): + return None + _static_assets = ["shiny-python-simple_files"] _static_assets = {"/" + sa: Path(__file__).parent / sa for sa in _static_assets} diff --git a/docs/dashboards/_examples/inputs/app.py b/docs/dashboards/_examples/inputs/app.py index 6ff6f55454..42841e9a12 100644 --- a/docs/dashboards/_examples/inputs/app.py +++ b/docs/dashboards/_examples/inputs/app.py @@ -1,43 +1,71 @@ # This file generated by Quarto; do not edit by hand. +# shiny_mode: core from __future__ import annotations from pathlib import Path from shiny import App, Inputs, Outputs, Session, ui +import seaborn as sns +penguins = sns.load_dataset("penguins") +species = list(penguins["species"].value_counts().index) +islands = list(penguins["island"].value_counts().index) + +# ======================================================================== + def server(input: Inputs, output: Outputs, session: Session) -> None: - from shiny import ui, render - import seaborn as sns - penguins = sns.load_dataset("penguins") + from shiny import reactive + from shiny.express import render, ui + ui.input_checkbox_group( + "species", "Species:", + species, selected = species + ) + + # ======================================================================== + + ui.input_checkbox_group( + "islands", "Islands:", + islands, selected = islands + ) # ======================================================================== - ui.input_select("x", "Variable:", - choices=["bill_length_mm", "bill_depth_mm"]) - ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) + ui.input_select("dist", "Distribution:", choices=["kde", "hist"]) ui.input_checkbox("rug", "Show rug marks", value = False) # ======================================================================== + @reactive.calc + def filtered_penguins(): + data = penguins[penguins["species"].isin(input.species())] + data = data[data["island"].isin(input.islands())] + return data + + # ======================================================================== + @render.plot - def displot(): - sns.displot( - data=penguins, hue="species", multiple="stack", - x=input.x(), rug=input.rug(), kind=input.dist()) + def depth(): + return sns.displot( + filtered_penguins(), x = "bill_depth_mm", + hue = "species", kind = input.dist(), + fill = True, rug=input.rug() + ) # ======================================================================== + return None + -_static_assets = ["toolbar_files"] +_static_assets = ["column-layout_files"] _static_assets = {"/" + sa: Path(__file__).parent / sa for sa in _static_assets} app = App( - Path(__file__).parent / "toolbar.html", + Path(__file__).parent / "column-layout.html", server, static_assets=_static_assets, ) diff --git a/docs/dashboards/_examples/inputs/card-toolbar.qmd b/docs/dashboards/_examples/inputs/card-toolbar.qmd index 16192c042a..ac23c3fe85 100644 --- a/docs/dashboards/_examples/inputs/card-toolbar.qmd +++ b/docs/dashboards/_examples/inputs/card-toolbar.qmd @@ -11,7 +11,7 @@ penguins = sns.load_dataset("penguins") ```{python} #| content: card-sidebar -from shiny import ui, render +from shiny.express import ui, render ui.input_select("x", "Variable:", choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) diff --git a/docs/dashboards/_examples/inputs/column-layout.qmd b/docs/dashboards/_examples/inputs/column-layout.qmd index 5586d25ffb..694a5fe97d 100644 --- a/docs/dashboards/_examples/inputs/column-layout.qmd +++ b/docs/dashboards/_examples/inputs/column-layout.qmd @@ -16,7 +16,8 @@ islands = list(penguins["island"].value_counts().index) ::: {.inputs header-for="next" layout-ncol="3"} ```{python} -from shiny import render, reactive, ui +from shiny import reactive +from shiny.express import render, ui ui.input_checkbox_group( "species", "Species:", species, selected = species diff --git a/docs/dashboards/_examples/inputs/inline-sidebar.qmd b/docs/dashboards/_examples/inputs/inline-sidebar.qmd index ca1eed43b3..e8d1997252 100644 --- a/docs/dashboards/_examples/inputs/inline-sidebar.qmd +++ b/docs/dashboards/_examples/inputs/inline-sidebar.qmd @@ -16,7 +16,7 @@ penguins = sns.load_dataset("penguins") ### {.sidebar} ```{python} -from shiny import render, ui +from shiny.express import render, ui ui.input_select("x", "Variable:", choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) diff --git a/docs/dashboards/_examples/inputs/inline-toolbar.qmd b/docs/dashboards/_examples/inputs/inline-toolbar.qmd index a44f918252..69300161da 100644 --- a/docs/dashboards/_examples/inputs/inline-toolbar.qmd +++ b/docs/dashboards/_examples/inputs/inline-toolbar.qmd @@ -1,7 +1,7 @@ --- title: "Palmer Penguins" author: "Cobblepot Analytics" -format: +format: dashboard: orientation: columns server: shiny @@ -13,12 +13,12 @@ penguins = sns.load_dataset("penguins") ``` -## Column +## Column ### {.toolbar} ```{python} -from shiny import render, ui +from shiny.express import render, ui ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) ui.input_checkbox("rug", "Show rug marks", value = False) ``` diff --git a/docs/dashboards/_examples/inputs/input-panel.qmd b/docs/dashboards/_examples/inputs/input-panel.qmd index 8ee6d4bcb5..82e71b00f1 100644 --- a/docs/dashboards/_examples/inputs/input-panel.qmd +++ b/docs/dashboards/_examples/inputs/input-panel.qmd @@ -21,7 +21,7 @@ penguins = sns.load_dataset("penguins") ```{python} #| content: card-toolbar -from shiny import render, ui +from shiny.express import render, ui ui.input_select("x", "Variable:", choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) diff --git a/docs/dashboards/_examples/inputs/page-sidebar.qmd b/docs/dashboards/_examples/inputs/page-sidebar.qmd index 8c6340ca59..73b1e1d74f 100644 --- a/docs/dashboards/_examples/inputs/page-sidebar.qmd +++ b/docs/dashboards/_examples/inputs/page-sidebar.qmd @@ -12,7 +12,7 @@ penguins = sns.load_dataset("penguins") ## {.sidebar} ```{python} -from shiny import render, ui +from shiny.express import render, ui ui.input_select("x", "Variable:", choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) diff --git a/docs/dashboards/_examples/inputs/right-sidebar.qmd b/docs/dashboards/_examples/inputs/right-sidebar.qmd index 88eb4b8bb5..b1e7584594 100644 --- a/docs/dashboards/_examples/inputs/right-sidebar.qmd +++ b/docs/dashboards/_examples/inputs/right-sidebar.qmd @@ -7,7 +7,8 @@ server: shiny ```{python} #| context: setup -from shiny import render, reactive, ui +from shiny import reactive +from shiny.express import render, ui import seaborn as sns penguins = sns.load_dataset("penguins") species = list(penguins["species"].value_counts().index) diff --git a/docs/dashboards/_examples/inputs/toolbar.qmd b/docs/dashboards/_examples/inputs/toolbar.qmd index f23a99a626..dda7f8918a 100644 --- a/docs/dashboards/_examples/inputs/toolbar.qmd +++ b/docs/dashboards/_examples/inputs/toolbar.qmd @@ -5,7 +5,7 @@ server: shiny --- ```{python} -from shiny import ui, render +from shiny.express import ui, render import seaborn as sns penguins = sns.load_dataset("penguins") ``` diff --git a/docs/dashboards/_examples/shiny-global-sidebar.qmd b/docs/dashboards/_examples/shiny-global-sidebar.qmd index 9c948994d6..ec88f86a5d 100644 --- a/docs/dashboards/_examples/shiny-global-sidebar.qmd +++ b/docs/dashboards/_examples/shiny-global-sidebar.qmd @@ -18,7 +18,8 @@ islands = list(penguins["island"].value_counts().index) ![](images/penguins.png){width="80%"} ```{python} -from shiny import render, reactive, ui +from shiny import reactive +from shiny.express import render, ui ui.input_checkbox_group( "species", "Species:", diff --git a/docs/dashboards/_examples/shiny-python-simple.qmd b/docs/dashboards/_examples/shiny-python-simple.qmd index 8c6340ca59..73b1e1d74f 100644 --- a/docs/dashboards/_examples/shiny-python-simple.qmd +++ b/docs/dashboards/_examples/shiny-python-simple.qmd @@ -12,7 +12,7 @@ penguins = sns.load_dataset("penguins") ## {.sidebar} ```{python} -from shiny import render, ui +from shiny.express import render, ui ui.input_select("x", "Variable:", choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) diff --git a/docs/dashboards/_examples/shiny-sidebar.qmd b/docs/dashboards/_examples/shiny-sidebar.qmd index 6271b16694..b2b14feb92 100644 --- a/docs/dashboards/_examples/shiny-sidebar.qmd +++ b/docs/dashboards/_examples/shiny-sidebar.qmd @@ -18,7 +18,8 @@ islands = list(penguins["island"].value_counts().index) ![](images/penguins.png){width="80%"} ```{python} -from shiny import render, reactive, ui +from shiny import reactive +from shiny.express import render, ui ui.input_checkbox_group( "species", "Species:", diff --git a/docs/dashboards/_inputs.qmd b/docs/dashboards/_inputs.qmd index cc3015769a..7055c787a1 100644 --- a/docs/dashboards/_inputs.qmd +++ b/docs/dashboards/_inputs.qmd @@ -8,13 +8,13 @@ Sidebars are a great place to group inputs for Shiny interactive dashboards. To title: "Sidebar" format: dashboard --- - + ## {.sidebar} ```{{python}} ``` -## Column +## Column ```{{python}} ``` @@ -36,7 +36,7 @@ If you have a dashboard with [multiple pages](#pages), you may want the sidebar title: "Sidebar" format: dashboard --- - + # {.sidebar} Sidebar content @@ -64,11 +64,11 @@ title: "Toolbar" format: dashboard server: shiny --- - + ## {.toolbar} - + ```{{python}} -from shiny import ui, render +from shiny.express import ui, render ui.input_select("x", "Variable:", choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) @@ -97,12 +97,12 @@ title: "Toolbar" format: dashboard server: shiny --- - + # {.toolbar} Toolbar content -# Page 1 +# Page 1 ```{{python}} ``` @@ -118,11 +118,11 @@ Toolbar content In some cases you may want to marry inputs more directly to a single output. To do this, define a card toolbar immediately above the cell that generates the output. You can do this by either adding the `content: card-toolbar` option to a cell or by creating a div with the `.card-toolbar` class. For example: -```` {.python .pymd} +```` {.python .pymd} ```{{python}} #| title: Penguin Bills #| content: card-toolbar -from shiny import ui, render +from shiny.express import ui, render ui.input_select("x", "Variable:", choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) diff --git a/docs/dashboards/data-display.qmd b/docs/dashboards/data-display.qmd index 4cf58fd9be..62de7ed385 100644 --- a/docs/dashboards/data-display.qmd +++ b/docs/dashboards/data-display.qmd @@ -370,7 +370,7 @@ Use the `ui.value_box()` function within a function decorated with `@render.ui`. ```` python ```{{python}} -from shiny import render, ui +from shiny.express import render, ui @render.ui def value(): return ui.value_box("Value", input.value()) diff --git a/docs/dashboards/interactivity/shiny-python/_shiny-advanced.md b/docs/dashboards/interactivity/shiny-python/_shiny-advanced.md index dda9d81167..b0a526351d 100644 --- a/docs/dashboards/interactivity/shiny-python/_shiny-advanced.md +++ b/docs/dashboards/interactivity/shiny-python/_shiny-advanced.md @@ -9,7 +9,8 @@ server: shiny # <1> ```{{python}} # <2> #| context: setup import seaborn as sns -from shiny import render, reactive, ui +from shiny import reactive +from shiny.express import render, ui penguins = sns.load_dataset("penguins") ``` # <2> diff --git a/docs/dashboards/interactivity/shiny-python/_shiny-sidebar.md b/docs/dashboards/interactivity/shiny-python/_shiny-sidebar.md index 399ae2f069..94b21de599 100644 --- a/docs/dashboards/interactivity/shiny-python/_shiny-sidebar.md +++ b/docs/dashboards/interactivity/shiny-python/_shiny-sidebar.md @@ -18,7 +18,7 @@ penguins = sns.load_dataset("penguins") ## {.sidebar} # <2> ```{{python}} -from shiny import render, ui +from shiny.express import render, ui ui.input_select("x", "Variable:", # <3> choices=["bill_length_mm", "bill_depth_mm"]) ui.input_select("dist", "Distribution:", choices=["hist", "kde"]) diff --git a/docs/dashboards/interactivity/shiny-python/index.qmd b/docs/dashboards/interactivity/shiny-python/index.qmd index 44f0c5c25a..4517465676 100644 --- a/docs/dashboards/interactivity/shiny-python/index.qmd +++ b/docs/dashboards/interactivity/shiny-python/index.qmd @@ -135,7 +135,8 @@ However, sometimes we have code that would be excessive to run for every user, a ```{{python}} #| context: setup import seaborn as sns -from shiny import render, reactive, ui +from shiny import reactive +from shiny.express import render, ui penguins = sns.load_dataset("penguins") ``` ```` From 03322f82b92487fe489ae24807c664d2d4ef2353 Mon Sep 17 00:00:00 2001 From: Winston Chang Date: Thu, 14 Mar 2024 16:15:03 -0500 Subject: [PATCH 2/2] Update version requirements --- .../interactivity/shiny-python/_shiny-requirements.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dashboards/interactivity/shiny-python/_shiny-requirements.qmd b/docs/dashboards/interactivity/shiny-python/_shiny-requirements.qmd index 9534f28278..e5e2077684 100644 --- a/docs/dashboards/interactivity/shiny-python/_shiny-requirements.qmd +++ b/docs/dashboards/interactivity/shiny-python/_shiny-requirements.qmd @@ -2,7 +2,7 @@ ::: {.callout-note} ### Shiny Prerequisites -In order to use Shiny within Quarto documents you will need the latest version of the `shiny` (>=0.6.1) and `shinywidgets` (>=0.2.2) packages. You can install the latest version of these with: +In order to use Shiny within Quarto documents you will need the latest version of the `shiny` (>=0.9.0) and `shinywidgets` (>=0.3.1) packages. You can install the latest version of these with: ```{.bash} pip install --upgrade shiny shinywidgets