add separate section for Bioconductor classes and methods

_bookdown.yml

@@ -8,7 +8,8 @@ rmd_files: ["index.Rmd",
            "devguide-introduction.Rmd",
            "package-name.Rmd",
            "general-package-development.Rmd",
-	         "important-bioc-features.Rmd",
+           "important-bioc-features.Rmd",
+           "bioc-classes-methods.Rmd",
            "readme-file.Rmd",
            "description-file.Rmd",
            "namespace-file.Rmd",

bioc-classes-methods.Rmd

@@ -0,0 +1,90 @@
+# Common Bioconductor Methods and Classes {#reusebioc}
+
+## Motivation {#bioc-common-motivation}
+
+Bioconductor is a large and diverse project with many packages that provide
+functionality for a wide range of biological data types and statistical methods.
+It has a rich set of classes and methods that are widely used across
+many packages. It is, therefore, important to reuse existing data classes and
+methods to ensure that packages are inter-operable with the rest of the
+_Bioconductor_ software ecosystem. Central data representations allow users to
+readily integrate analysis workflows across multiple Bioconductor packages
+providing a more seamless user experience.
+
+Many classes in Bioconductor are implemented using the S4 object-oriented
+system in R. The S4 system is particularly well-suited for the representation
+of complex genomic data structures. The initial motivations to use S4 in
+Bioconductor were centered around its benefits over other systems such as S3.
+These benefits include, but are not limited to, formal class definitions,
+multiple inheritance, and validity checking.
+
+Although Bioconductor promotes the re-use of existing S4 classes to represent
+genomic data, there are cases where new classes are needed for cutting-edge
+technologies. In such cases, new classes should be developed, ideally, with
+open discussion and consideration of the Bioconductor community.
+
+### Use Case: Importing data {#commonimport}
+
+For developers who import data into their package, it is important to know which
+packages and methods are available for reuse. The following list provides
+commonly used packages and their methods to import various data types:
+
++ GTF, GFF, BED, BigWig, etc., -- `r BiocStyle::Biocpkg("rtracklayer")` `::import()`
++ VCF -- `r BiocStyle::Biocpkg("VariantAnnotation")` `::readVcf()`
++ SAM / BAM -- `r BiocStyle::Biocpkg("Rsamtools")` `::scanBam()`,
+  `r BiocStyle::Biocpkg("GenomicAlignments")` `::readGAlignment*()`
++ FASTA -- `r BiocStyle::Biocpkg("Biostrings")` `::readDNAStringSet()`
++ FASTQ -- `r BiocStyle::Biocpkg("ShortRead")` `::readFastq()`
++ MS data (XML-based and mgf formats) -- `r BiocStyle::Biocpkg("Spectra")` `::Spectra()`, 
+  `r BiocStyle::Biocpkg("Spectra")` `::Spectra(source = MsBackendMgf::MsBackendMgf())`
+
+This list is not exhaustive, and developers are encouraged to initiate dialogue
+with other community members to identify additional packages and methods that
+may be useful for their specific use case. We acknowledge that class and method
+discoverability can be a challenge and we are working to improve this aspect of
+the Bioconductor project.
+
+### Common Classes {#commonclass}
+
+The following table, though certainly not exhaustive, provides select classes
+and constructor functions to represent genomic data:
+
+| Data Type                     | Package and Function                                     | Description                                            |
+|-------------------------------|----------------------------------------------------------|--------------------------------------------------------|
+| Rectangular feature by sample | `r BiocStyle::Biocpkg("SummarizedExperiment")` `::SummarizedExperiment()` | RNAseq count matrix, microarray, etc. |
+| Genomic coordinates           | `r BiocStyle::Biocpkg("GenomicRanges")` `::GRanges()` | 1-based, closed interval genomic coordinates |
+| Genomic coordinates (multiple)| `r BiocStyle::Biocpkg("GenomicRanges")` `::GRangesList()` | Genomic coordinates from multiple samples |
+| Ragged genomic coordinates    | `r BiocStyle::Biocpkg("RaggedExperiment")` `::RaggedExperiment()` | Ragged (variable length) genomic coordinates |
+| DNA/RNA/AA sequences          | `r BiocStyle::Biocpkg("Biostrings")` `::*StringSet()` | DNA, RNA, or amino acid sequences |
+| Gene sets | `r BiocStyle::Biocpkg("BiocSet")` `::BiocSet()`, <br>`r BiocStyle::Biocpkg("GSEABase")` `::GeneSet()`, <br>`r BiocStyle::Biocpkg("GSEABase")` `::GeneSetCollection()` | Collections of gene sets |
+| Multi-omics data              | `r BiocStyle::Biocpkg("MultiAssayExperiment")` `::MultiAssayExperiment()` | Data integrating multiple omics assays |
+| Single cell data              | `r BiocStyle::Biocpkg("SingleCellExperiment")` `::SingleCellExperiment()` | Single-cell expression and related data |
+| Mass spec data                | `r BiocStyle::Biocpkg("Spectra")` `::Spectra()` | Mass spectrometry data                               |
+| File formats                  | `r BiocStyle::Biocpkg("BiocIO")` `::BiocFile-class` | Classes for interacting with various biological data file formats |
+
+Search [biocViews][] for other classes and methods that may be useful for your
+package.
+
+## Package Submission Considerations
+
+Bioconductor strives for interoperability across packages and strongly
+encourages that package submissions reuse existing Bioconductor classes and
+methods. Packages that do not follow this guideline may be asked to revise
+their code to use existing classes and methods.
+
+In the case where the data does not conform to an existing data class,
+we recommend discussing the design of a new class with the Bioconductor
+community. The open discussion can take place on main Bioconductor communication
+channels such as the [bioc-devel][bioc-devel-mail] mailing list, or the
+Bioconductor community slack.
+
+## Package Implementations
+
+The following packages are examples of packages that reuse Bioconductor classes
+and methods:
+
+| package | inherits classes and methods from: |
+|---|---|
+| `r BiocStyle::Biocpkg("DESeq2")` | `r BiocStyle::Biocpkg("SummarizedExperiment")`, `r BiocStyle::Biocpkg("GenomicRanges")` |
+| `r BiocStyle::Biocpkg("GenomicAlignments")` | `r BiocStyle::Biocpkg("GenomicRanges")`, `r BiocStyle::Biocpkg("Rsamtools")` |
+| `r BiocStyle::Biocpkg("VariantAnnotation")` | `r BiocStyle::Biocpkg("GenomicRanges")`, `r BiocStyle::Biocpkg("SummarizedExperiment")`, `r BiocStyle::Biocpkg("Rsamtools")` |

important-bioc-features.Rmd

@@ -71,55 +71,11 @@ acceptable list, please email <bioc-devel@r-project.org> requesting the new
 `biocViews` term, under which hierarchy the term should be placed, and the
 justification for the new term.
 
+## Common Bioconductor Methods and Classes
 
-## Common Bioconductor Methods and Classes {#reusebioc}
-
-We strongly recommend reusing existing methods for importing data, and
-reusing established classes for representing data. Here are some
-suggestions for importing different file types and commonly used
-_Bioconductor_ classes. For more classes and functionality also try
-searching in [biocViews][] for your data type.
-
-### Importing data {#commonimport}
-
-+ GTF, GFF, BED, BigWig, etc., -- `r BiocStyle::Biocpkg("rtracklayer")` `::import()`
-+ VCF -- `r BiocStyle::Biocpkg("VariantAnnotation")` `::readVcf()`
-+ SAM / BAM -- `r BiocStyle::Biocpkg("Rsamtools")` `::scanBam()`,
-  `r BiocStyle::Biocpkg("GenomicAlignments")` `::readGAlignment*()`
-+ FASTA -- `r BiocStyle::Biocpkg("Biostrings")` `::readDNAStringSet()`
-+ FASTQ -- `r BiocStyle::Biocpkg("ShortRead")` `::readFastq()`
-+ MS data (XML-based and mgf formats) -- `r BiocStyle::Biocpkg("Spectra")` `::Spectra()`, 
-  `r BiocStyle::Biocpkg("Spectra")` `::Spectra(source = MsBackendMgf::MsBackendMgf())`
-
-
-### Common Classes {#commonclass}
-
-+ Rectangular feature x sample data --
-  `r BiocStyle::Biocpkg("SummarizedExperiment")` `::SummarizedExperiment()`
-  (RNAseq count matrix, microarray, ...)
-+ Genomic coordinates -- `r BiocStyle::Biocpkg("GenomicRanges")` `::GRanges()`
-  (1-based, closed interval)
-+ Genomic coordinates from multiple samples --
-  `r BiocStyle::Biocpkg("GenomicRanges")` `::GRangesList()`
-+ Ragged genomic coordinates -- `r BiocStyle::Biocpkg("RaggedExperiment")`
-  `::RaggedExperiment()`
-+ DNA / RNA / AA sequences -- `r BiocStyle::Biocpkg("Biostrings")`
-  `::*StringSet()`
-+ Gene sets -- `r BiocStyle::Biocpkg("BiocSet")` `::BiocSet()`,
-  `r BiocStyle::Biocpkg("GSEABase")` `::GeneSet()`,
-  `r BiocStyle::Biocpkg("GSEABase")` `::GeneSetCollection()`
-+ Multi-omics data --
-  `r BiocStyle::Biocpkg("MultiAssayExperiment")` `::MultiAssayExperiment()`
-+ Single cell data --
-  `r BiocStyle::Biocpkg("SingleCellExperiment")` `::SingleCellExperiment()`
-+ Spatial transcriptomics data --
-  `r BiocStyle::Biocpkg("SpatialExperiment")` `::SpatialExperiment()`
-+ Mass spec data -- `r BiocStyle::Biocpkg("Spectra")` `::Spectra()`
-+ File formats -- `r BiocStyle::Biocpkg("BiocIO")` `` ::`BiocFile-class` ``
-
-
-In general, a package will not be accepted if it does not show interoperability
-with the current [_Bioconductor_][] ecosystem.
+Visit the [Common Bioconductor Methods and Classes][bioc-common] page for a
+list of common methods and classes used in Bioconductor packages and for
+a more in-depth overview for supporting Bioconductor classes in packages.
 
 ## Vignette {#bioc-vignette}