Tidy user interface #2 (#180)

* Tidy user interface

Co-authored-by: Luke Zappia <lazappi@users.noreply.github.com>

* Update docs

Co-authored-by: Luke Zappia <lazappi@users.noreply.github.com>

* update docs

* fix linting issues

---------

Co-authored-by: Luke Zappia <lazappi@users.noreply.github.com>

NAMESPACE

@@ -1,15 +1,10 @@
 # Generated by roxygen2: do not edit by hand
 
 export(AnnData)
-export(InMemoryAnnData)
 export(from_Seurat)
 export(from_SingleCellExperiment)
 export(generate_dataset)
 export(read_h5ad)
-export(to_HDF5AnnData)
-export(to_InMemoryAnnData)
-export(to_Seurat)
-export(to_SingleCellExperiment)
 export(write_h5ad)
 importFrom(Matrix,as.matrix)
 importFrom(Matrix,sparseMatrix)

R/AbstractAnnData.R

@@ -9,6 +9,8 @@
 #'   Abstract [R6][R6::R6Class] class representing an AnnData
 #'   object. Defines the interface.
 #' @importFrom R6 R6Class
+#'
+#' @noRd
 AbstractAnnData <- R6::R6Class("AbstractAnnData", # nolint
   active = list(
     #' @field X NULL or an observation x variable matrix (without

R/AnnData.R

@@ -1,53 +1,6 @@
-#' An AnnData object
+#' Create an in-memory AnnData object.
 #'
-#' @description An AnnData object. This class can either be an in-memory
-#' AnnData (InMemoryAnnData) or an HDF5-backed AnnData (HDF5AnnData). The
-#' AnnData object stores a data matrix `X` together with annotations of
-#' observations `obs` (`obsm`, `obsp`) and variables `var` (`varm`, `varp`).
-#' Additional layers of data can be stored in `layers` and unstructured
-#' annotations in `uns`.
-#'
-#' @section Functions that can be used to create AnnData objects:
-#'
-#'   * [AnnData()]: Create an in-memory AnnData object.
-#'   * [read_h5ad()]: Read an HDF5-backed AnnData file from disk.
-#'   * [from_SingleCellExperiment()]: Convert a SingleCellExperiment object to an AnnData object.
-#'   * [from_Seurat()]: Convert a Seurat object to an AnnData object.
-#'
-#' @section Slots:
-#'
-#' * `X`: A matrix of observations by variables.
-#' * `obs`: A data frame of observations.
-#' * `var`: A data frame of variables.
-#' * `obs_names`: Names of observations (alias for `rownames(obs)`).
-#' * `var_names`: Names of variables (alias for `rownames(var)`).
-#' * `layers`: A named list of matrices with the same dimensions as `X`.
-#' * `obsm`: A named list of matrices with the same number of rows as `obs`.
-#' * `varm`: A named list of matrices with the same number of rows as `var`.
-#' * `obsp`: A named list of sparse matrices with the same number of rows and columns as the number of observations.
-#' * `varp`: A named list of sparse matrices with the same number of rows and columns as the number of variables.
-#' * `uns`: A named list of unstructured annotations.
-#'
-#' @section Methods:
-#'
-#' * `print()`: Print a summary of the AnnData object.
-#' * `shape()`: Dimensions (observations x variables) of the AnnData object.
-#' * `n_obs()`: Number of observations in the AnnData object.
-#' * `n_vars()`: Number of variables in the AnnData object.
-#' * `obs_keys()`: Column names of `obs`.
-#' * `var_keys()`: Column names of `var`.
-#' * `layers_keys()`: Element names of `layers`.
-#' * `obsm_keys()`: Element names of `obsm`.
-#' * `varm_keys()`: Element names of `varm`.
-#' * `obsp_keys()`: Element names of `obsp`.
-#' * `varp_keys()`: Element names of `varp`.
-#'
-#' @section Conversion methods:
-#'
-#' * `to_SingleCellExperiment()`: Convert to SingleCellExperiment.
-#' * `to_Seurat()`: Convert to Seurat.
-#' * `to_InMemoryAnnData()`: Convert to an InMemory AnnData.
-#' * `to_HDF5AnnData()`: Convert to an HDF5 Backed AnnData.
+#' For more information on the functionality of an AnnData object, see [anndataR-package].
 #'
 #' @param X Either `NULL` or a observation × variable matrix with
 #'   dimensions consistent with `obs` and `var`.
@@ -77,9 +30,7 @@
 #' @param shape Shape tuple (#observations, #variables). Can be provided
 #'   if `X` or `obs` and `var` are not provided.
 #'
-#' @return An [AbstractAnnData] object.
-#'
-#' @seealso [AbstractAnnData]
+#' @return An in-memory AnnData object.
 #'
 #' @export
 #'
@@ -98,6 +49,8 @@
 #' )
 #'
 #' adata
+#'
+#' @seealso [anndataR-package]
 AnnData <- function(
     X = NULL,
     obs = NULL,

R/HDF5AnnData.R

@@ -2,6 +2,7 @@
 #'
 #' @description
 #' Implementation of an in memory AnnData object.
+#' @noRd
 HDF5AnnData <- R6::R6Class("HDF5AnnData", # nolint
   inherit = AbstractAnnData,
   cloneable = FALSE,
@@ -403,7 +404,7 @@ HDF5AnnData <- R6::R6Class("HDF5AnnData", # nolint
 #' @return An HDF5AnnData object with the same data as the input AnnData
 #'   object.
 #'
-#' @export
+#' @noRd
 #'
 #' @examples
 #' ad <- AnnData(

R/InMemoryAnnData.R

@@ -5,6 +5,8 @@
 #'
 #' @importFrom Matrix as.matrix
 #'
+#' @noRd
+#'
 #' @examples
 #' ## complete example
 #' ad <- AnnData(
@@ -23,7 +25,6 @@
 #'   obs = data.frame(row.names = letters[1:10]),
 #'   var = data.frame(row.names = LETTERS[1:5])
 #' )
-#' @export
 InMemoryAnnData <- R6::R6Class("InMemoryAnnData", # nolint
   inherit = AbstractAnnData,
   private = list(
@@ -290,7 +291,7 @@ InMemoryAnnData <- R6::R6Class("InMemoryAnnData", # nolint
 #' @return An InMemoryAnnData object with the same data as the input AnnData
 #'   object.
 #'
-#' @export
+#' @noRd
 #'
 #' @examples
 #' ad <- AnnData(

R/Seurat.R

@@ -1,14 +1,12 @@
-#' @rdname Seurat
+#' Convert a Seurat object to an AnnData object
 #'
-#' @title Convert Between AnnData and Seurat
-#'
-#' @description `to_Seurat()` converts an AnnData object to a Seurat object.
+#' `to_Seurat()` converts an AnnData object to a Seurat object.
 #'
 #' @param obj An AnnData object
 #'
 #' @importFrom Matrix t
 #'
-#' @export
+#' @noRd
 #' @examples
 #' ad <- AnnData(
 #'   X = matrix(1:5, 3L, 5L),
@@ -100,11 +98,13 @@ to_Seurat <- function(obj) { # nolint
   names
 }
 
-#' @rdname Seurat
+#' Convert a Seurat object to an AnnData object
 #'
-#' @description `from_Seurat()` converts a Seurat object to an AnnData object.
+#' `from_Seurat()` converts a Seurat object to an AnnData object.
 #' Only one assay can be converted at a time.
 #'
+#' For more information on the functionality of an AnnData object, see [anndataR-package].
+#'
 #' @param seurat_obj An object inheriting from Seurat.
 #' @param output_class Name of the AnnData class. Must be one of `"HDF5AnnData"` or `"InMemoryAnnData"`.
 #' @param assay Assay to be converted. If NULL, `DefaultAssay()` is used.
@@ -114,8 +114,18 @@ to_Seurat <- function(obj) { # nolint
 #' @param ... Additional arguments passed to the generator function.
 #'
 #' @export
-# TODO: add tests with Seurat objects not created by anndataR
-from_Seurat <- function(seurat_obj, output_class = c("InMemoryAnnData", "HDF5AnnData"), assay = NULL, X = "counts", ...) { # nolint
+#'
+#' @seealso [anndataR-package]
+# TODO: Add examples
+# nolint start: object_name_linter
+from_Seurat <- function(
+    # nolint end: object_name_linter
+    seurat_obj,
+    output_class = c("InMemoryAnnData", "HDF5AnnData"),
+    assay = NULL,
+    X = "counts",
+    ...) {
+  output_class <- match.arg(output_class)
 
   stopifnot(inherits(seurat_obj, "Seurat"))
 

R/SingleCellExperiment.R

@@ -1,15 +1,14 @@
-#' @rdname SingleCellExperiment
+#' Convert an AnnData object to a SingleCellExperiment object
 #'
-#' @title Convert Between AnnData and SingleCellExperiment
-#'
-#' @description `to_SingleCellExperiment()` converts an AnnData object
+#' `to_SingleCellExperiment()` converts an AnnData object
 #'   to a SingleCellExperiment.
 #'
 #' @param object an AnnData object, e.g., InMemoryAnnData
 #'
 #' @return `to_SingleCellExperiment()` returns a SingleCellExperiment
 #'   representing the content of `object`.
 #'
+#' @noRd
 #' @examples
 #' if (interactive()) {
 #'   ## useful when interacting with the SingleCellExperiment !
@@ -28,8 +27,6 @@
 #' ## construct a SingleCellExperiment from an AnnData object
 #' sce <- to_SingleCellExperiment(ad)
 #' sce
-#'
-#' @export
 to_SingleCellExperiment <- function(object) { # nolint
   stopifnot(
     inherits(object, "AbstractAnnData")
@@ -89,9 +86,9 @@ to_SingleCellExperiment <- function(object) { # nolint
   sce
 }
 
-#' @rdname SingleCellExperiment
+#' Convert a SingleCellExperiment object to an AnnData object
 #'
-#' @description `from_SingleCellExperiment()` converts a
+#' `from_SingleCellExperiment()` converts a
 #'   SingleCellExperiment to an AnnData object.
 #'
 #' @param sce An object inheriting from SingleCellExperiment.
@@ -107,6 +104,12 @@ to_SingleCellExperiment <- function(object) { # nolint
 #'
 #' @examples
 #' ## construct an AnnData object from a SingleCellExperiment
+#' library(SingleCellExperiment)
+#' sce <- SingleCellExperiment(
+#'   assays = list(counts = matrix(1:5, 5L, 3L)),
+#'   colData = DataFrame(cell = 1:3),
+#'   rowData = DataFrame(gene = 1:5)
+#' )
 #' from_SingleCellExperiment(sce, "InMemory")
 #'
 #' @export
@@ -120,6 +123,8 @@ from_SingleCellExperiment <- function(
     inherits(sce, "SingleCellExperiment")
   )
 
+  output_class <- match.arg(output_class)
+
   # fetch generator
   generator <- get_anndata_constructor(output_class)
 

R/anndataR-package.R

@@ -1,5 +1,63 @@
 #' @keywords internal
 #' @importFrom methods as
+#'
+#' @description An AnnData object. This class can either be an in-memory
+#' AnnData (InMemoryAnnData) or an HDF5-backed AnnData (HDF5AnnData). The
+#' AnnData object stores a data matrix `X` together with annotations of
+#' observations `obs` (`obsm`, `obsp`) and variables `var` (`varm`, `varp`).
+#' Additional layers of data can be stored in `layers` and unstructured
+#' annotations in `uns`.
+#'
+#' @section Functions that can be used to create AnnData objects:
+#'
+#'   * [AnnData()]: Create an in-memory AnnData object.
+#'   * [read_h5ad()]: Read an HDF5-backed AnnData file from disk.
+#'   * [from_SingleCellExperiment()]: Convert a SingleCellExperiment object to an AnnData object.
+#'   * [from_Seurat()]: Convert a Seurat object to an AnnData object.
+#'
+#' @section An AnnData object has the following slots:
+#'
+#' Access them by using the `$` operator. Example: `adata$obs`.
+#'
+#' * `X`: A matrix of observations by variables.
+#' * `obs`: A data frame of observations.
+#' * `var`: A data frame of variables.
+#' * `obs_names`: Names of observations (alias for `rownames(obs)`).
+#' * `var_names`: Names of variables (alias for `rownames(var)`).
+#' * `layers`: A named list of matrices with the same dimensions as `X`.
+#' * `obsm`: A named list of matrices with the same number of rows as `obs`.
+#' * `varm`: A named list of matrices with the same number of rows as `var`.
+#' * `obsp`: A named list of sparse matrices with the same number of rows and columns as the number of observations.
+#' * `varp`: A named list of sparse matrices with the same number of rows and columns as the number of variables.
+#' * `uns`: A named list of unstructured annotations.
+#'
+#' @section An AnnData object has the following methods:
+#'
+#' Access them by using the `$` operator. Example: `adata$write_h5ad()`.
+#'
+#' * `print()`: Print a summary of the AnnData object.
+#' * `shape()`: Dimensions (observations x variables) of the AnnData object.
+#' * `n_obs()`: Number of observations in the AnnData object.
+#' * `n_vars()`: Number of variables in the AnnData object.
+#' * `obs_keys()`: Column names of `obs`.
+#' * `var_keys()`: Column names of `var`.
+#' * `layers_keys()`: Element names of `layers`.
+#' * `obsm_keys()`: Element names of `obsm`.
+#' * `varm_keys()`: Element names of `varm`.
+#' * `obsp_keys()`: Element names of `obsp`.
+#' * `varp_keys()`: Element names of `varp`.
+#' * `uns_keys()`: Element names of `uns`.
+#' * `write_h5ad()`: Write the AnnData object to an HDF5 file.
+#'
+#' @section Conversion methods:
+#'
+#' Access them by using the `$` operator. Example: `adata$to_Seurat()`.
+#'
+#' * `to_SingleCellExperiment()`: Convert to SingleCellExperiment.
+#' * `to_Seurat()`: Convert to Seurat.
+#' * `to_InMemoryAnnData()`: Convert to an InMemory AnnData.
+#' * `to_HDF5AnnData()`: Convert to an HDF5 Backed AnnData.
+#'
 "_PACKAGE"
 
 ## usethis namespace: start

R/read_h5ad.R

@@ -13,8 +13,10 @@
 #'   * `w` creates a file, truncating any existing ones.
 #'   * `w-`/`x` are synonyms, creating a file and failing if it already exists.
 #'
-#' @param ... Extra arguments provided to [to_SingleCellExperiment()] or
-#'   [to_Seurat()]
+#' @param ... Extra arguments provided to `adata$to_SingleCellExperiment()` or
+#'   `adata$to_Seurat()`. See [AnnData()] for more information on the arguments of
+#'   these functions. Note: update this documentation when
+#'   [`r-lib/roxygen2#955`](https://github.com/r-lib/roxygen2/issues/955) is resolved.
 #'
 #' @return The object specified by `to`
 #' @export