608 private links
I have a Quarto project of manuscript type with notebooks that generate tables and figures. And I would like to include specific tables from any notebook in the main manuscript index.qmd
.
In tackling this question I was constrained by the following factor:
- never
{{< include ... >}}
a notebook into the main manuscript, because I found no way to do that without polluting the main manuscript with the entire contents of said notebook. This was unacceptable to me since the whole point of separating analysis into separate files was to keep the main manuscript "clean" and easy to work with for some co-authors who might not need or want to see all the plumbing.
A figure from a notebook is easily included in the main manuscript with {{< embed /notebooks/notebook.qmd#fig-id >}}
which renders the plot, its caption and (assuming you defined a label
) also numbers it and makes it cross-referable. Unfortunately no such mechanism is offered for tables (I assume because tables are not stand-alone image files that can easily be embedded).
Here is the hack of a solution that I arrived at after wrestling with this today. As far as I know I have not seen this particular approach mentioned anywhere else before.
In the notebook
Create a Markdown table using knitr::kable
and save the output (i.e., the rendered Markdown table) to a file on disk, for example:
sas.fityk.params %>%
select(temperature, diameter, starts_with("fit.")) %>%
knitr::kable(col.names = c("$d/\\unit{\\nm}$", "$T_\\text{a}/\\unit{\\degreeCelsius}$",
"SSR", "WSSR", "DoF", "WSSR/DoF", "$R^2$"), digits = c(0, 1, 1, 2, 1, 1, 1, 6),
align = c("l", "l", "l", "l", "l", "l", "l", "l")) %T>%
print() %>%
saveRDS(file = here("assets/objects/tab-sas-fitinfo.rds"))
Note that print
is necessary if you want to also render the table in the notebook's output.
And since the Markdown will be handled by pandoc we can also use LaTeX math. But another effect of this being Markdown is that the Quarto -> MathJax pipeline is never involved, so more complex LaTeX cannot be used. I wonder if there's a way to force Quarto to handle a particular chunk even if it would normally just be passed on to pandoc...?
In the main manuscript
```{r}
#| results: asis
this.cap <- paste("Goodness of fit parameters for the anti-Stokes/Stokes spectra.")
this.lbl <- "{#tbl-sas-fitinfo}"
cat(c(
readRDS(file = here("assets/objects/tab-sas-fitinfo.rds")),
paste(paste0("\n", ":"), this.cap, this.lbl, "\n")),
sep = "\n")
```
This re-produces the same table as in the notebook, and with a numbered table caption that can be cross-referenced. This works in rendered HTML output and even works in PDF (by some magic). I don't care too much about DOCX right now, so that's success!
Avenues that did not work
My first idea was to simply print the Markdown table in a chunk with a tbl-cap
:
```{r}
#| results: asis
#| tbl-cap: Goodness of fit parameters for the anti-Stokes/Stokes spectra.
# label: tbl-sas-fitinfo
readRDS(file = here("assets/objects/tab-sas-fitinfo.rds"))
```
but this simply results in a Quarto error (apparently triggered by the presence of label
):
Error running filter /usr/lib/rstudio-server/bin/quarto/share/filters/main.lua:
Block, list of Blocks, or compatible element expected, got table
That prompted me to try printing the caption line manually, but that too fails, surprisingly:
```{r}
#| results: asis
this.cap <- paste("Goodness of fit parameters for the anti-Stokes/Stokes spectra.")
this.lbl <- "{#tbl-sas-fitinfo}"
cat(paste(paste0("\n", ":"), this.cap, this.lbl, "\n"))
readRDS(file = here("assets/objects/tab-sas-fitinfo.rds"))
```
Turns out that in the intermediate Markdown file created by Quarto, every line in the chunk is printed inside its own fenced block, and thus the caption line becomes syntactically separate from the table itself.
The solution (as shown above) is to print the caption line and the table itself in a single command.
Links
- https://github.com/quarto-dev/quarto-cli/discussions/2052 - How to gracefully mix Markdown and latex tables?
- https://github.com/quarto-dev/quarto-cli/discussions/11067 - How to include pre-rendered tables?
- https://forum.posit.co/t/tables-numbering-in-quarto/196413 - tables numbering in quarto
- https://github.com/quarto-dev/quarto-cli/discussions/9334 - debugging advice for main.lua errors
- https://stackoverflow.com/questions/74097579/make-figure-text-bold-in-quarto-figure-captions - Make "Figure" text bold in quarto figure captions
- https://scholar.social/@solarchemist/114678486113073128
sessionInfo
$ quarto check # slightly cleaned-up output
Quarto 1.5.57
[✓] Checking versions of quarto binary dependencies...
Pandoc version 3.2.0: OK
Dart Sass version 1.70.0: OK
Deno version 1.41.0: OK
Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
Version: 1.5.57
Path: /usr/lib/rstudio-server/bin/quarto/bin
[✓] Checking tools....................OK
TinyTeX: (not installed)
Chromium: (not installed)
[✓] Checking LaTeX....................OK
Using: Installation From Path
Path: /usr/local/texlive/2023/bin/x86_64-linux
Version: 2023
[✓] Checking basic markdown render....OK
[✓] Checking Python 3 installation....OK
Version: 3.10.12
Path: /usr/bin/python3
Jupyter: (None)
[✓] Checking R installation...........OK
Version: 4.5.0
Path: /opt/R/4.5.0/lib/R
knitr: 1.50
rmarkdown: 2.29
[✓] Checking Knitr engine render......OK
This solves a major shortcoming when authoring documents in Quarto or R Markdown that generate both PDF and HTML output. MathJax lets the author use LaTeX commands in the source that translate into proper output in the HTML, but before this work there was no support for siunitx
v3. This work can be said to take over where burnpanck/MathJax-siunitx left off.
To use it, I copied siunitx.js from its repo to my Quarto project and then made Quarto add it to the published site by setting the following in the project/document YAML:
project:
resources:
- "path/to/siunitx.js"
format:
html:
html-math-method:
method: mathjax
url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"
include-in-header:
text: |
<script>
window.MathJax = {
loader: {
load: ['[custom]/siunitx.js', '[tex]/html'],
paths: { custom: './path/to/' }
},
tex: {
packages: { '[+]': ['siunitx', 'html'] },
siunitx: {
'per-mode': 'power'
}
}
};
</script>
And that should give you siunitx
v3 commands in your Quarto manuscript :-)
Note that if you also want your notebooks to benefit from siunitx-pcc, you will need to symlink (or copy) the siunitx.js
file into their top-level directory (which is ./notebooks
) or otherwise siunitx macros will not render as paths: { custom: './path/to/' }
is relative to their top-level directory and not (as you might think) the Quarto project root.
I have found that re-creating the directory structure mkdir -p notebooks/path/to; cd notebooks/path/to
and then symlinking ln -s ../../../path/to/siunitx.js .
works (don't forget to add another resources line: - "notebooks/path/to/siunitx.js"
).
In short, siunitx-pcc lets you use almost all siunitx
macros.
- https://github.com/limefrogyank/siunitx-pcc
- https://github.com/quarto-dev/quarto-cli/discussions/6168#discussioncomment-11545200
- https://github.com/mathjax/MathJax-third-party-extensions/issues/47
- https://github.com/burnpanck/MathJax-siunitx/issues/14
- https://github.com/burnpanck/MathJax-siunitx/issues/13
- https://old.reddit.com/r/LaTeX/comments/1bj8p7c/whats_your_experience_transitioning_to_quarto/m1p0m4p
Markdown
- JupyText: Jupyter notebooks as Markdown documents
- Generate Google Slides from Markdown
- CriticMarkup - plaintext editing markup for humans
R Markdown
- https://github.com/rstudio/rmarkdown
- R Markdown: The Definitive Guide by Yihui Xie, J. J. Allaire and Garrett Grolemund (2020)
- Authoring books and technical documents with R Markdown by Yihui Xie (2021)
- Create blogs and websites with R Markdown
- Writing reproducible geoscience papers using R Markdown, Docker, and Gitlab by Daniel Nüst, Vicky Steeves, Rémi Rampin, Markus Konkol, Edzer Pebesma (2018)
pandoc
- https://pandoc.org/extras.html
- https://github.com/LaurentRDC/pandoc-plot
- A pandoc-based layout workflow for scholarly journals by Piero (2018)
Quarto
Quarto, by RStudio, sorry, Posit, a new scientific and technical publishing system.
Something to consider, especially if you are new to the field and aren't already invested in the earlier systems.
Adopted by the Journal of Cheminformatics (Aug 2020)
- First adoption by a scientific journal announced in editorial by Egon Willighagen
- Blog post by Willighagen on the same subject
- CiTO updates (another blog post by WIllighagen)
- Citation Typing: progress but we need more uptake
- CiTO updates #4: annotations in datasets
- FAIR blog-to-blog citations
- CiTO for blog citations
BioMedCentral on the CiTO Pilot (seems to only include Journal of Cheminformatics, for now).
Usage of CiTO is spreading. This page keeps track of CiTO annotation in Wikidata.
What about adoption by tools?
Willighagen offers rudimental instructions for BibTeX (but probably only suitable for Journal of Cheminformatics at the moment) as well as for Google Docs + Zotero (not really working) in this github repo.
Markdown template with CiTO for the Journal of Cheminformatics.
The best tool with support for CiTO: pandoc scholar
Pandoc Scholar appears to be our best bet at the moment if we want to use CiTO in our manuscripts.
Krewinkel A, Winkler R. 2017. Formatting Open Science: agilely creating multiple document formats for academic manuscripts with Pandoc Scholar. PeerJ Computer Science 3:e112 https://doi.org/10.7717/peerj-cs.112
Other notes
It looks like support for CiTO should happen at the document processing tool stage, and not in our reference managers (Zotero, etc.).
I wonder if something like Biber/BibLaTeX should add support for CiTO, or if that's the wrong abstraction level.
Martin Fenner has a blog post from 2011 (Google Cache) where he shows how to use CiTO with a Wordpress plugin, unfortunately both the post and the plugin appear to have gone offline.
Recently, ORCID promoted Scite_ on their blog. But Scite describes itself as a Brooklyn-based startup (I assume that's code for venture capital-backed), although it also acknowledges funding from public institutions such as NSF and NIH. Scite uses "a deep learning model" to identify "citations that display the context of the citation and describe whether the article provides supporting or contrasting evidence" (so they really only classify the citation as supporting or contrasting). In contrast to Scite, CiTO is an open standard that anyone can build on. Although Scite is currently much glitzier and fancier than anything CiTO can provide, we should encourage everyone to use CiTO (if they care about citation classification).