Package Conventions

Want to add a code to Seurat? This document is intended to provide a description of the expected behavior/naming conventions for functions and their parameters.

Code Style

In general, we try to follow Google's R Style Guide, with the following exceptions and additions:

• Use curly braces for every if/else statement, for/while loop, and function definition (including anonymous for use in apply)
• Function documentation should use Roxygen syntax
• All arguments, except the ..., should be named in function calls (eg. use print(x = 'hello') instead of print('hello'))

Diagnostic Output

Parameter Name

In the function definition, include a verbose parameter to allow the user to specify whether to print the output. This should take a boolean.

Printing to console

If the function is write any output to the console, there are several options to choose from to print messages. Here's what you should use and when:

• message: Should be the default, except in the cases listed below.
• cat: Use when designing a show method or any print.* S3 methods.
• warning: Function is allowed to proceed but user should be notified (higher priority notification than message)
• stop: Function should quit and print this message.
• print: Never use print

Progress Bars

Progress bars are great. If you want to add a progress bar to a function that uses:

• for loops - initialize the progress bar with:

pb <- txtProgressBar(char = '=', style = 3)

And update in each loop iteration with:

setTxtProgressBar(pb = pb, value = i)

• apply - use functions from the pbapply package.

• c++ code, use the RcppProgress package. Include the header file #include <progress.hpp> and

// [[Rcpp::depends(RcppProgress)]] in the .cpp file. In the function, create the progress bar with

Progress p(num_iterations, display_progress); 

and update with

p.increment();

Plotting Functions

Plotting functionality should be kept separate from any computation where possible. If the function can optionally produce plots (e.g. FindVariableGenes), the parameter controlling this should be named do.plot. When possible, plotting functions should using the ggplot2 framework over base R or other custom plotting frameworks.

Return value

All plotting functions that use ggplot2 to generate the plots should return the ggplot object. For constructing composite ggplot plots , we recommend using the plot_grid function from the cowplot package.

Parameter options for all plots

All plotting functions should have the following parameter options (if applicable) to allow for easy manipulation of the plot:

• plot.title - accept a string for the plot title
• pt.size - accepts a numeric to adjust the point size
• reduction.use - accepts a string to select the dimensional reduction to use
• group.by - accepts a string to set the grouping variable
• remove.legend - accepts a boolean to toggle the legend off, default should be FALSE
• legend.position - accepts a string to change the legend position
• dark.theme - accepts a boolean to toggle on the dark theme, default should be FALSE
• cell.use - accepts a vector of cell names to allowing plotting a subset of cells