Vignette Guidelines

Vignette Guidelines

All methods for SeuratWrappers must have a vignette showcasing the method's use on a Seurat object

Vignette Structure and Placement

All vignettes should be written in Rmarkdown, placed in the docs/ directory, and named for the method added (eg. fast_mnn.Rmd, which corresponds to fast_mnn.R). Vignettes should showcase the method run on one or more datasets. We provide several example datasets that can be used for these vignettes. If each dataset is standalone (not dependent on analysis of another dataset), we encourage the use of tabs break up the document.

Citation

Please have citation information for the method at the top of the vignette. We do this using quote blocks

> *Paper title*
>
> Author list
>
> Journal, Year.
>
> doi: [doi number][doi link]
>
> Website: https://web.site

The website can be either the source code repository, the CRAN or Bioconductor page, or a website for the method itself. Please change the tag to GitHub, CRAN, or Bioconductor when the website is one of those locations.

Knitr Options

We generally use the following knitr options for our vignettes

knitr::opts_chunk$set(
  tidy = TRUE,
  tidy.opts = list(width.cutoff = 95),
  message = FALSE,
  warning = FALSE
)

Please feel free to use your own options.

Output Formats

We encourage all vignettes to output both HTML and Markdown documents. The HTML documents have nice formatting and tab support while the Markdown documents are renderable by GitHub, useful for easy browsing the docs/ directory. We use the html_document output format, as we feel it looks nicer than the html_vignette format, and the github_document for Markdown to ensure it renders nicely on GitHub. Please note, for the github_document output format, figures are stored in vignette_files/figure-markdown_github directory. These figures in this directory should be committed with the vignette.

To have the same Rmarkdown source knit to both formats, simply specify them in the YAML header and use rmarkdown::render on the command line to knit the documents

output:
  github_document:
    html_preview: true
    toc: true
    toc_depth: 3
  html_document:
    df_print: kable

Rscript -e "rmarkdown::render('vignette.Rmd', output_format = 'all')"

Other output formats, such as PDFs, are accepted. However, these two formats tend to be the most user-accessible.

Example Data

For an example dataset, we encourage the use of one of the datasets provided by SeuratData. These datasets are used by Seurat for their vignettes and are easy to distribute to other users. If none of the datasets in SeuratData are sufficient to demonstrate your tool's functionality, let us know, and you can use another publicly available dataset.