bioconductor-submission

# 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 ```r # 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 = "email@institution.edu", 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: ```r # 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 ```r # Set license usethis::use_mit_license() # Or manually in DESCRIPTION License: Artistic-2.0 ``` ## BiocCheck Validation ### Installing BiocCheck ```r if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install("BiocCheck") ``` ### Running BiocCheck ```r # 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: ```r # Bad ```{r, eval=FALSE} result <- analyze_data(data) ``` # Good - provide real example data ```{r} 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: ```r # 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**: ```r usethis::use_news_md() ``` Content: ```markdown # 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**: ```r #' 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 ```r #' 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 ```r #' 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 ```r #' @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 ```r --- title: "Introduction to MyBiocPackage" author: - name: Your Name affiliation: Institution email: email@institution.edu 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) ``` ```{r style, echo=FALSE, results='asis'} BiocStyle::markdown()