Package Conventions

Interesting in adding code to Seurat? We have an internal style guide that we try to follow to maintain coding consistency across developers, copied below. We encourage you to consider them when adding to the package.

Code Style

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

• Function documentation should use Roxygen syntax
• For clarity, 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 in the .cpp file.

#include <progress.hpp>
// [[Rcpp::depends(RcppProgress)]]

In the function, create the progress bar with

Progress p(num_iterations, display_progress); 

and update with

p.increment();

Plotting functions

We suggest that plotting functions using 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.

To allow for easy interoperability with our plotting functions, we suggest the following arguments for plotting functions

• pt.size - accepts a numeric to adjust the point size
• reduction - accepts a string to select the dimensional reduction to use
• group.by - accepts a string to set the grouping variable

• cells - accepts a vector of cell names to allowing plotting a subset of cells

Any task that can be done by adding components to a ggplot object should not be part of the plotting function. For example, adding a dark theme or removing a legend can be done with ggplot2's theme (or DarkTheme and NoLegend in Seurat). As such, these tasks should be handled outside of the plotting function.

Accessing and Modifying internal slots

We have provided accessor(GetXXX)/mutator(SetXXX) functions for accessing and setting internal slots.