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 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

• 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 FALSE
• legend.position - accepts a string to change the legend position
• dark.theme - accepts a boolean to toggle on the dark theme, default FALSE
• cells.use - accepts a vector of cell names to allowing plotting a subset of cells

Accessing and Modifying internal slots

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