There are a number of methods to create a Phrase doc from programming languages, together with R Markdown and the official package deal with R and the python-docx library in Python. However one of many latest and most intriguing is Quarto, a free and open supply technical publishing system from RStudio (now Posit) that’s native to Python and Julia, in addition to R.
One of many nice benefits of Quarto is that, not like a Phrase-specific package deal, the identical Quarto file with minor changes can be utilized to generate dozens of output codecs along with Phrase, together with PowerPoint, HTML, and PDF. (Be taught extra: “What’s Quarto? RStudio Implements Subsequent-Era R Markdown.”) As well as, you may automate the creation of Phrase reviews and embrace the outcomes of your evaluation and visualization code.
Here is the best way to use Quarto to create Phrase paperwork.
Step 1: Set up Quarto
Since Quarto shouldn’t be a language-specific library, it installs like another stand-alone software program. You could find binary downloads for Home windows, macOS, and Linux on Quarto’s “Get Began” web page.
If you’re an R person and have an up-to-date model of RStudio, Quarto ought to be included by default. You do not want to put in Quarto individually.
If you wish to use Quarto in Visible Studio Code, set up the Quarto extension along with the Quarto utility software program. To render Quarto paperwork that embrace Python code, my system additionally instructed me to put in Jupyter Pocket book by working
python3 -m pip set up jupyter.
You may create and render Quarto recordsdata with any plain textual content editor and your terminal, similar to with R or Python scripts, since they’re plain textual content recordsdata and never binary. Nevertheless, you’ll miss out on all of the built-in instruments of an IDE, equivalent to code completion hints and a render button.
Step 2: Create a quarto doc file
After getting put in Quarto, you may create a brand new Quarto archive in your IDE within the common manner, both
File > New File > Quarto Doc (No Quarto Presentation) in RStudio, or
File > New File in VS Code and select “Quarto” because the language.
In RStudio, it is possible for you to to select from just a few doc output codecs in Quarto. Choose Phrase and you’ll mechanically generate a pattern Phrase doc or a clean doc. It might be useful till you might be aware of the Quarto syntax to see what the pattern appears to be like like.
The default YAML header in RStudio features a title, an output format (on this case, docx for Phrase), and an editor (visible WYSIWYG or font).
If you happen to’re beginning with a clean doc in VS Code, you may add the essential YAML header to the highest:
title: "Your doc title"
So far as I do know, there isn’t any WYSIWYG Quarto editor in VS Code, so there isn’t any cause to specify an editor.
Then begin creating your content material.
Step 3 – Add Textual content Utilizing Markdown Syntax
Quarto makes use of Pandoc’s model of Markdown syntax to put in writing textual content. That features single underscores round textual content you need italicized, double asterisks for textual content you wish to daring, clean strains between paragraphs, two or extra areas on the finish of a line to create a line break, and hash symbols firstly. of a line to point the font measurement of the heading. A single hash signifies the most important font measurement, h1; two is the second largest, h2; and so.
Step 4 (optionally available): Model your doc from a reference .docx
Some CSS-based doc types designed for Quarto’s HTML output codecs won’t work when exporting to Phrase. Nevertheless, you may create a separate reference type Phrase doc with font types, sizes, and so forth in your doc.
The next code ought to be run in your Terminal (not the R console or Python) to create a default Phrase type doc, on this instance known as my_doc_style.docx (you may name it no matter you want):
quarto pandoc -o my-doc-style.docx --print-default-data-file reference.docx
This creates a daily Phrase .docx file, not a Microsoft Phrase .dotx template. You may open your referenced .docx and customise its types similar to with any Phrase doc by opening the Kinds panel from the Phrase ribbon.
A use the template in a Quarto doc, add it to the YAML header of the doc with syntax like this:
format: docx: reference-doc: my-doc-style.docx
There are different customizations out there for Quarto Phrase paperwork, equivalent to including a desk of contents or part numbering, which you’ll be able to view within the Quarto for Phrase documentation.
Step 5 – Add the outcomes of the R or Python code to your Phrase doc
The most effective issues about producing a Phrase doc from R or Python is the flexibility to run code and add output to your doc, together with charts.
To do that, add code snippets to your Quarto file, that are activated by three backticks, like this for R:
# R code right here
or this for Python:
# Python code right here
you may configure choices for a bit of code, equivalent to displaying the code (echo), executing the code (eval), displaying code warning messages, and many others. Snippet choices begin with
#| (sometimes called a “hash pipe”) for R, Python, or Julia.
The snippet choices beneath would show outcomes of R code in a bit however do not present the code within the phrase doc:
#| echo: false
#| eval: true
# R code right here
Different choices embrace
#| fig-cap: My caption for a foot determine,
#| warning: false to not show any warning messages when the code is executed, and
#| cache: true to cache the outcomes of a computationally intensive chunk the place the information won’t change.
You may run code contained in the determine caption possibility utilizing
!expr with syntax like
#| fig-cap: !expr paste("Knowledge pulled on"Sys.Date())
Step 6 – Render the doc
You may render a Quarto doc in RStudio or VS Code utilizing the Render button, the keyboard shortcut
Ctrl/Cmd + Shift + Ok or do it with terminal command
quarto render my_quarto_document.qmd --to docx
for a doc known as my_quarto_document.
R customers can even use the command from the quarto R package deal
Word: Sometimes, the preliminary Phrase doc Advance that appeared in RStudio in earlier variations did not all the time present my graph. That appears to be mounted. Nevertheless, if that occurs to you, strive duplicating the preliminary .docx file as a brand new editable Phrase doc, as that mounted the difficulty for me.
Step 7 (Optionally available): Automate A number of Variations with Parameters
Having the ability to create Phrase recordsdata with the outcomes of your code is helpful not just for one-time paperwork. It additionally permits you to streamline common knowledge reporting and updates with code that pulls new knowledge from an exterior supply, runs new calculations, and generates up to date charts with a single processing name.
However Quarto additionally has the flexibility so as to add parameters to a report, that are like externally outlined variables throughout rendering. That permits you to use a report as a template and create the identical report for various parameters like cities or areas. For instance, if you might want to run a report for every of 10 cities,
metropolis may very well be outlined as a parameter within the YAML header of your doc, like
--- title: "My Quarto Doc" params: metropolis: New York ---
That units a parameter known as metropolis with a default worth of New York. You may then entry the worth of town parameter in your R code with
#| echo: false
cat("This report is about", params$metropolis)
To create a number of reviews in R utilizing the identical Quarto doc however totally different values for the parameter, I normally create a perform to render my doc after which use the purrr package deal
stroll() perform to run my perform on an inventory of things. For instance, if my parameterized Quarto doc is named params_test.qmd with a parameter known as metropolis, this may very well be my rendering perform in R:
render_my_doc <- perform(the_city = "New York", the_doc = "params_test.qmd")
quarto::quarto_render(enter = the_doc, execute_params = checklist("metropolis" = the_city),
output_file = paste0("test_", the_city, ".docx"), output_format = "docx")
And that is how I might use my perform to generate three separate paperwork for New York, Chicago, and Los Angeles:
stroll(checklist("New York", "Chicago", "Los Angeles"), render_my_doc)
Python’s syntax is a bit totally different and is predicated on the Papermill library. For instance, defining a parameter is completed in a snippet of Python code that may seem like this
```python #| tags: [parameters] metropolis = 'Boston' ```
You may learn extra about parameterizing Python paperwork within the Quarto Parameters documentation.
If you happen to’re all in favour of R and extra R suggestions, head over to the Do Extra with R! web page.