bioconductor-submission

name	bioconductor-submission
description	Bioconductor-specific package submission requirements, BiocCheck validation, version numbering, and review process beyond standard CRAN requirements

Bioconductor Submission Guide

This skill covers submitting packages to Bioconductor, which has additional requirements beyond CRAN. Bioconductor is the primary repository for computational biology and bioinformatics R packages.

Rules

1. Version scheme: Use x.y.z where y is even for release, odd for devel
2. biocViews required: Must include appropriate biocViews terms in DESCRIPTION
3. BiocCheck must pass: Run BiocCheck::BiocCheck() and fix all errors/warnings
4. Vignettes must run: No eval=FALSE for all chunks; use real data
5. S4 classes preferred: Use S4 for complex data structures
6. BiocStyle for vignettes: Use BiocStyle package for consistent formatting
7. Use BiocManager::install(): Not install.packages() in documentation
8. Submit via GitHub issue: To Bioconductor/Contributions repository
9. Active maintenance required: Must respond to build reports and issues
10. Follow Bioconductor guidelines: Read package guidelines thoroughly

Bioconductor vs CRAN

When to Submit to Bioconductor

Submit to Bioconductor if your package:

• Analyzes genomic data (sequences, annotations, variants)
• Analyzes high-throughput biological data (microarrays, RNA-seq, proteomics)
• Provides infrastructure for biological data types
• Integrates with existing Bioconductor packages
• Uses Bioconductor data structures (SummarizedExperiment, GenomicRanges, etc.)

When to Submit to CRAN

Submit to CRAN if your package:

• Provides general statistical methods
• Doesn't specifically work with biological data
• Doesn't depend on Bioconductor packages
• Is a general-purpose tool that happens to be useful for biology

Note: Packages can be on both, but start with one.

Version Numbering Scheme

Bioconductor uses a specific version numbering system:

Version Format: x.y.z

• x (major): Rarely changes; major redesign
• y (minor): Even for release, odd for devel
• z (patch): Bug fixes and minor updates

Examples

# Initial development
0.99.0  -> Start here for new packages
0.99.1  -> Bug fixes during review
0.99.2  -> More fixes

# First release (Bioconductor assigns this)
1.0.0   -> First Bioc release version

# Development continues
1.1.0   -> Devel version after 1.0.0 release

# Next release cycle
1.2.0   -> Next Bioc release (even y)
1.3.0   -> Devel version after 1.2.0

# Bug fixes
1.2.1   -> Bug fix for release
1.3.1   -> Bug fix for devel

Version Management

# Start new package
Version: 0.99.0

# During review, bump z for fixes
Version: 0.99.1
Version: 0.99.2

# After acceptance, Bioconductor core sets
Version: 1.0.0  # For next release

# You continue development
Version: 1.1.0  # Devel version

Critical: Don't manually set version to 1.0.0 - Bioconductor does this.

DESCRIPTION File Requirements

Complete Bioconductor DESCRIPTION

Package: MyBiocPackage
Title: Analysis of Single-Cell RNA Sequencing Data
Version: 0.99.0
Authors@R: c(
    person("First", "Last",
           email = "[e-mail]",
           role = c("aut", "cre"),
           comment = c(ORCID = "0000-0001-2345-6789")),
    person("Second", "Author",
           role = "aut",
           comment = c(ORCID = "0000-0001-2345-6780"))
    )
Description: Provides methods for analyzing single-cell RNA sequencing
    data. Implements novel clustering algorithms and visualization
    techniques. Integrates with Bioconductor infrastructure including
    SingleCellExperiment and other core data structures.
License: Artistic-2.0
Encoding: UTF-8
LazyData: false
Depends:
    R (>= 4.4.0)
Imports:
    BiocGenerics,
    S4Vectors,
    SummarizedExperiment,
    SingleCellExperiment,
    methods,
    stats,
    graphics
Suggests:
    BiocStyle,
    knitr,
    rmarkdown,
    testthat (>= 3.0.0),
    scRNAseq
biocViews: Software, SingleCell, RNASeq, Clustering, Visualization,
    DimensionReduction, GeneExpression
VignetteBuilder: knitr
RoxygenNote: 7.3.0
Roxygen: list(markdown = TRUE)
URL: https://github.com/username/MyBiocPackage
BugReports: https://github.com/username/MyBiocPackage/issues

biocViews Requirements

Every Bioconductor package must have appropriate biocViews terms:

# Find appropriate terms
BiocManager::install("biocViews")
library(biocViews)

# Browse available terms
data(biocViewsVocab)
biocViewsVocab

# Common top-level categories
# Software - computational tools
# AnnotationData - annotation packages
# ExperimentData - example/experiment data packages
# Workflow - workflow packages

Common biocViews Terms

Software packages:

biocViews: Software, RNASeq, GeneExpression, Transcriptomics,
    DifferentialExpression, Sequencing, Coverage, Alignment

By technology:

• RNASeq, ChIPSeq, ATACSeq, DNASeq, MethylSeq
• Microarray, Proteomics, Metabolomics
• SingleCell, SpatialData, MultiChannel

By analysis type:

• DifferentialExpression, Clustering, Classification
• Normalization, Preprocessing, QualityControl
• Visualization, Annotation, GenomeAnnotation

By data type:

• GeneExpression, Epigenetics, StructuralVariation
• CopyNumberVariation, SNP, Transcriptomics

License Requirements

Bioconductor prefers open-source licenses:

• Artistic-2.0 (recommended for Bioconductor)
• GPL (>= 2)
• LGPL
• MIT
• BSD

# Set license
usethis::use_mit_license()
# Or manually in DESCRIPTION
License: Artistic-2.0

BiocCheck Validation

Installing BiocCheck

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("BiocCheck")

Running BiocCheck

# Basic check
BiocCheck::BiocCheck()

# More detailed
BiocCheck::BiocCheck(".", new.package = TRUE)

# For package updates
BiocCheck::BiocCheck(".", new.package = FALSE)

Understanding BiocCheck Output

BiocCheck reports three levels:

• ERROR: Must fix (will prevent acceptance)
• WARNING: Should fix (reviewers will ask)
• NOTE: Consider fixing (good practice)

Common BiocCheck Issues and Fixes

1. Version Number Issues

Problem:

ERROR: Version number must be 0.99.0 for new packages

Fix:

# In DESCRIPTION
Version: 0.99.0

2. biocViews Missing

Problem:

ERROR: Package must have biocViews

Fix:

# Add to DESCRIPTION
biocViews: Software, Sequencing, RNASeq

3. Vignette eval=FALSE

Problem:

WARNING: Vignette chunks should not use eval=FALSE

Fix: Make vignettes actually run:

# Bad
```{r, eval=FALSE}
result <- analyze_data(data)

Good - provide real example data

data("example_dataset")
result <- analyze_data(example_dataset)

#### 4. Non-BiocStyle Vignette

**Problem**:

NOTE: Consider using BiocStyle package

**Fix**:
```yaml
---
title: "Package Vignette"
author: "Your Name"
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Package Vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r style, echo=FALSE, results='asis'}
BiocStyle::markdown()

#### 5. install.packages() in Documentation

**Problem**:

WARNING: Use BiocManager::install() not install.packages()

**Fix**:
```r
# Bad
#' Install with: install.packages("MyPackage")

# Good
#' Install with: BiocManager::install("MyPackage")

6. Long Line Lengths

Problem:

NOTE: Lines should be <= 80 characters

Fix: Break long lines:

# Use styler
styler::style_pkg()

# Or manually
result <- my_function(
    argument1 = value1,
    argument2 = value2,
    argument3 = value3
)

7. Missing NEWS File

Problem:

NOTE: Consider adding NEWS file

Fix:

usethis::use_news_md()

Content:

# MyBiocPackage 0.99.0

* Initial Bioconductor submission
* Implements core functionality for X
* Includes vignette demonstrating Y

8. Package Size Too Large

Problem:

WARNING: Package size is X MB

Fix:

• Remove large example data
• Create separate data package
• Compress data files
• Use external data with ExperimentHub

9. Using .Rbuildignore Incorrectly

Problem:

WARNING: Don't use .Rbuildignore excessively

Fix: Only ignore truly unnecessary files:

^.*\.Rproj$
^\.Rproj\.user$
^\.github$
^_pkgdown\.yml$
^docs$
^pkgdown$

10. Missing runnable examples

Problem:

ERROR: All exported functions must have runnable examples

Fix:

#' My Function
#'
#' @examples
#' # Load example data
#' data("example_data")
#'
#' # Run analysis
#' result <- my_function(example_data)
#'

#' @export
my_function <- function(x) {
    # implementation
}

S4 Classes and Methods

Bioconductor strongly encourages S4 for complex data structures:

Defining S4 Classes

#' MyData Class
#'
#' @slot counts matrix of counts
#' @slot metadata data.frame of sample metadata
#' @slot features data.frame of feature metadata
#'
#' @export
setClass("MyData",
    slots = c(
        counts = "matrix",
        metadata = "data.frame",
        features = "data.frame"
    )
)

S4 Constructor

#' Create MyData Object
#'
#' @param counts matrix of counts
#' @param metadata data.frame of metadata
#' @param features data.frame of features
#'
#' @return MyData object
#'
#' @examples
#' counts <- matrix(rpois(100, 10), nrow=10)
#' metadata <- data.frame(sample=paste0("S", 1:10))
#' features <- data.frame(gene=paste0("G", 1:10))
#' obj <- MyData(counts, metadata, features)
#'

#' @export
MyData <- function(counts, metadata, features) {
    new("MyData",
        counts = counts,
        metadata = metadata,
        features = features
    )
}

S4 Methods

#' @export
setGeneric("getCounts", function(x) standardGeneric("getCounts"))

#' @export
setMethod("getCounts", "MyData", function(x) x@counts)

#' @export
setMethod("show", "MyData", function(object) {
    cat("MyData object\n")
    cat("  Samples:", ncol(object@counts), "\n")
    cat("  Features:", nrow(object@counts), "\n")
})

Vignette Requirements

BiocStyle Vignette Template

---
title: "Introduction to MyBiocPackage"
author:
  - name: Your Name
    affiliation: Institution
    email: [e-mail]
date: "`r Sys.Date()`"
output:
  BiocStyle::html_document:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Introduction to MyBiocPackage}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning = FALSE, message = FALSE)

BiocStyle::markdown()

Introduction

This vignette demonstrates the basic usage of r Biocpkg("MyBiocPackage").

Installation

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("MyBiocPackage")

Quick Start

library(MyBiocPackage)

# Load example data
data("example_data")

# Run analysis
result <- analyze(example_data)

Session Info

sessionInfo()

### Using Example Data

Create example data for vignettes:

```r
# In R/data.R
#' Example Single-Cell Dataset
#'
#' @description
#' A subset of single-cell RNA-seq data for demonstration.
#'
#' @format A SingleCellExperiment object with 100 cells and 500 genes
#' @examples
#' data("example_sce")
#' example_sce
"example_sce"

# Create and save data
# In data-raw/example_sce.R
library(SingleCellExperiment)
set.seed(123)

counts <- matrix(rpois(50000, 5), nrow=500, ncol=100)
rownames(counts) <- paste0("Gene", 1:500)
colnames(counts) <- paste0("Cell", 1:100)

example_sce <- SingleCellExperiment(
    assays = list(counts = counts)
)

usethis::use_data(example_sce, overwrite = TRUE)

Submission Process

1. Pre-Submission Checklist

• Package passes R CMD check with no errors, warnings, or notes
• Package passes BiocCheck::BiocCheck() with no errors
• Version is 0.99.0 (for new packages)
• biocViews terms are appropriate and specific
• All vignette chunks run (no eval=FALSE)
• S4 classes used for complex data structures
• Vignette uses BiocStyle
• Examples use BiocManager::install()
• Package has runnable examples for all exported functions
• NEWS file exists and is up-to-date
• Package is on GitHub
• README.md is informative
• Package size is reasonable (<5 MB preferred)

2. GitHub Repository Setup

# Ensure package is on GitHub
usethis::use_github()

# Add required files
usethis::use_readme_md()
usethis::use_news_md()

# Add GitHub Actions
usethis::use_github_action("check-bioc")

3. Open Submission Issue

1. Go to https://github.com/Bioconductor/Contributions/issues/new/choose
2. Choose "Submit a new package"
3. Fill in the template:

## Package Name

MyBiocPackage

## Submitter Name

Your Name

## Submitter Email

[e-mail]

## Package Source

https://github.com/username/MyBiocPackage

## Confirmation

- [x] I understand that Bioconductor has a 6-month release cycle
- [x] I will maintain this package
- [x] I have read the package guidelines
- [x] My package passes BiocCheck

## Additional Information

This package provides methods for analyzing single-cell RNA-seq data.
It implements novel algorithms for clustering and visualization.

4. Review Process

Timeline:

1. Automated checks (immediate): GitHub Actions runs checks
2. Initial review (1-2 weeks): Reviewer assigned
3. Review iterations (varies): Address reviewer comments
4. Acceptance (after all issues resolved): Merged to Bioconductor

5. Responding to Reviews

Reviewers will comment on your issue. For each comment:

1. Make requested changes
2. Commit and push to GitHub
3. Reply to the specific comment with what you changed
4. Tag reviewer when all comments addressed

Example response:

@reviewer-name I've addressed this by:
- Adding more detailed documentation to `my_function()`
- Including an additional example
- Fixing the typo in the vignette

Commit: abc1234

6. Common Review Comments

Documentation:

• "Please add more details to the vignette"
• "Function X needs a more detailed description"
• "Add references to the methods section"

Code quality:

• "Consider using S4 classes for this data structure"
• "Use vapply instead of sapply"
• "Avoid using deprecated functions from package Y"

Examples:

• "Provide a complete, runnable example"
• "Example should demonstrate the main use case"
• "Add more comments to explain the workflow"

Dependencies:

• "Package X should be in Imports, not Suggests"
• "Do you really need all these dependencies?"
• "Consider using the Bioconductor version of package Y"

7. Post-Acceptance

After acceptance:

# Bioconductor will:
# 1. Fork your repository to their GitHub
# 2. Set up build servers
# 3. Assign version 1.0.0 for next release
# 4. Add to Bioconductor package list

# You continue development:
# 1. Push changes to YOUR GitHub repository
# 2. Changes propagate to Bioconductor every 24 hours
# 3. Monitor build reports
# 4. Respond to user issues

Package Types

Software Packages

Most common type:

• Provides tools for analysis
• Uses existing Bioconductor infrastructure
• biocViews: Software, ...

Annotation Packages

Provide biological annotations:

• Gene annotations
• Pathway databases
• Organism databases
• biocViews: AnnotationData, ...

Experiment Data Packages

Provide example or published datasets:

• Must be >2 MB
• Separate from software package
• biocViews: ExperimentData, ...

Workflow Packages

Step-by-step analysis workflows:

• Complete analysis examples
• Use multiple Bioconductor packages
• biocViews: Workflow, ...

Data Packages

Creating ExperimentData Package

# Structure
MyExperimentData/
  DESCRIPTION
  R/
    data.R
  data/
    dataset1.rda
    dataset2.rda
  vignettes/
    overview.Rmd
  man/
    dataset1.Rd

DESCRIPTION:

Package: MyExperimentData
Title: Example Data for MyBiocPackage
Version: 0.99.0
biocViews: ExperimentData, RNASeqData, SingleCellData
License: Artistic-2.0

Using ExperimentHub

For very large data (>50 MB):

# Create metadata
library(ExperimentHub)

# In inst/extdata/metadata.csv
# See ExperimentHub documentation

# Users download with:
library(ExperimentHub)
eh <- ExperimentHub()
mydata <- eh[["EH12345"]]

Common Pitfalls

1. Wrong Version Number

Problem: Using 1.0.0 for initial submission

Fix: Always use 0.99.0 for new packages

2. Non-Running Vignettes

Problem: Vignette chunks use eval=FALSE

Fix: Provide real example data and make vignettes run

3. Missing biocViews

Problem: Forgot to add biocViews to DESCRIPTION

Fix: Add appropriate terms from biocViews vocabulary

4. Using CRAN-style Installation

Problem: Documentation says install.packages()

Fix: Use BiocManager::install() everywhere

5. S3 When S4 Needed

Problem: Using S3 for complex data structures

Fix: Use S4 classes for anything non-trivial

6. Not Maintaining Package

Problem: Ignoring build reports after acceptance

Fix: Check build reports daily, fix issues promptly

7. Too Many Dependencies

Problem: Importing 30+ packages

Fix: Only import what you actually need

8. Large Package Size

Problem: Including large datasets in main package

Fix: Create separate ExperimentData package

9. Slow Vignettes

Problem: Vignette takes 10+ minutes to build

Fix: Use smaller example datasets, cache results

10. Ignoring Reviewer Comments

Problem: Not addressing all comments

Fix: Address every single comment, ask for clarification if needed

Additional Resources

Documentation

• Bioconductor Package Guidelines
• BiocCheck Documentation
• Package Submission Tracker

Tools

# Development tools
BiocManager::install("BiocCheck")
BiocManager::install("BiocStyle")

# Check package
BiocCheck::BiocCheck()

# Test locally
BiocManager::valid()

Getting Help

• Bioconductor Slack: https://bioc-community.herokuapp.com/
• Support site: https://support.bioconductor.org/
• Developer mailing list: [e-mail]

Key Differences from CRAN

Feature	CRAN	Bioconductor
Version scheme	x.y.z (any)	y even=release, odd=devel
Submission	Web form	GitHub issue
Review	Automated mostly	Human reviewer
Build cycle	On submission	Daily
Release cycle	Anytime	Every 6 months
Dependencies	Any CRAN package	Bioc or CRAN
Data structures	Any	S4 preferred
Vignette style	Any	BiocStyle preferred

This guide should help you successfully submit your package to Bioconductor!