[r] restore vignettes to docsite (in static HTML form)

.github/workflows/docsite-build-deploy.yml

@@ -31,33 +31,18 @@ jobs:
         run: |
           sudo apt-get install -y pandoc
 
-      - uses: r-lib/actions/setup-r@v2
-        with:
-          extra-repositories: https://tiledb-inc.r-universe.dev
-
-      - uses: r-lib/actions/setup-r-dependencies@v2
-        with:
-          working-directory: ./api/r/cellxgene.census
-          extra-packages: any::rcmdcheck, any::styler, any::roxygen2, any::pkgdown
-          needs: check
-          cache: true
-
       - name: Build Sphinx website
         run: |
           cd docs/
           make clean && make html
           cp -r _build/html/* ../docsite/.
 
-      - name: Build pkgdown website
-        run: |
-          cd api/r/cellxgene.census
-          Rscript -e 'pkgdown::build_site()'
-          cd ../../../
+          # Copy R pkgdown docs (static HTML checked into git)
           mkdir -p docsite/r
           cp -r api/r/cellxgene.census/docs/* docsite/r/.
 
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           folder: docsite # The folder the action should deploy.
-          branch: gh-pages
+          branch: gh-pages

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# MacOS system files
+*.DS_Store
+
 # Distribution / packaging
 .Python
 build/

api/r/cellxgene.census/.gitignore

@@ -1,6 +1,7 @@
 .Rproj.user
 .Rhistory
-docs
 inst/doc
 /doc/
 /Meta/
+# see vignettes_/README.md for explanation:
+vignettes

api/r/cellxgene.census/R/get_helpers.R

@@ -1,6 +1,6 @@
 #' Read the feature dataset presence matrix.
 #'
-#' @param census The census object, usually returned by `cellxgene.census::open_soma()`.
+#' @param census The census object from `cellxgene.census::open_soma()`.
 #' @param organism The organism to query, usually one of `Homo sapiens` or `Mus musculus`
 #' @param measurement_name The measurement object to query. Defaults to `RNA`.
 #'
@@ -10,6 +10,9 @@
 #' @export
 #'
 #' @examples
+#' census <- open_soma()
+#' on.exit(census$close(), add = TRUE)
+#' print(get_presence_matrix(census, "Homo sapiens")$dim())
 get_presence_matrix <- function(census, organism, measurement_name = "RNA") {
   exp <- get_experiment(census, organism)
   presence <- exp$ms$get(measurement_name)$get("feature_dataset_presence_matrix")

api/r/cellxgene.census/R/open.R

@@ -1,8 +1,9 @@
 #' Open the Cell Census
 #'
 #' @param census_version The version of the Census, e.g., "stable".
-#' @param uri The URI containing the Census SOMA objects. If specified, takes
-#'            precedence over `census_version`.
+#' @param uri A URI containing the Census SOMA objects to open instead of a
+#'            released version. (If supplied, takes precedence over
+#'            `census_version`.)
 #' @param tiledbsoma_ctx A `tiledbsoma::SOMATileDBContext` built using
 #'        `new_SOMATileDBContext_for_census()`. Optional (created automatically)
 #'        if using `census_version` and the context does not need to be reused.
@@ -16,6 +17,9 @@
 #' @export
 #'
 #' @examples
+#' census <- open_soma()
+#' as.data.frame(census$get("census_info")$get("summary")$read()$concat())
+#' census$close()
 open_soma <- function(census_version = "stable", uri = NULL, tiledbsoma_ctx = NULL) {
   if (is.null(uri) || is.null(tiledbsoma_ctx)) {
     description <- get_census_version_description(census_version)
@@ -45,18 +49,22 @@ DEFAULT_TILEDB_CONFIGURATION <- c(
 
 #' Create SOMATileDBContext for Cell Census
 #' @description Create a SOMATileDBContext suitable for using with `open_soma()`.
-#' Typically `open_soma()` creates a context automatically, but it can be created
-#' separately in order to set custom configuration options or to share it between
+#' Typically `open_soma()` creates a context automatically, but one can be created
+#' separately in order to set custom configuration options, or to share it between
 #' multiple open Census handles.
 #'
 #' @param census_version_description The result of `get_census_version_description()`
 #'        for the desired Census version.
 #' @param ... Custom configuration options.
 #'
-#' @return
+#' @return SOMATileDBContext object for `open_soma()`.
 #' @export
 #'
 #' @examples
+#' census_desc <- get_census_version_description("stable")
+#' ctx <- new_SOMATileDBContext_for_census(census_desc, "soma.init_buffer_bytes" = paste(4 * 1024**3))
+#' census <- open_soma("stable", tiledbsoma_ctx = ctx)
+#' census$close()
 new_SOMATileDBContext_for_census <- function(census_version_description, ...) {
   # start with default configuration
   cfg <- DEFAULT_TILEDB_CONFIGURATION

api/r/cellxgene.census/R/release_directory.R

@@ -9,6 +9,7 @@ CELL_CENSUS_RELEASE_DIRECTORY_URL <- "https://census.cellxgene.cziscience.com/ce
 #' @export
 #'
 #' @examples
+#' as.data.frame(get_census_version_description("stable"))
 get_census_version_description <- function(census_version) {
   census_directory <- get_census_version_directory()
   description <- census_directory[census_version, ]
@@ -32,6 +33,7 @@ get_census_version_description <- function(census_version) {
 #' @export
 #'
 #' @examples
+#' get_census_version_directory()
 get_census_version_directory <- function() {
   raw <- jsonlite::fromJSON(CELL_CENSUS_RELEASE_DIRECTORY_URL)
 

api/r/cellxgene.census/R/source_h5ad.R

@@ -12,6 +12,7 @@
 #' @export
 #'
 #' @examples
+#' get_source_h5ad_uri("0895c838-e550-48a3-a777-dbcd35d30272")
 get_source_h5ad_uri <- function(dataset_id, census_version = "stable", census = NULL) {
   description <- get_census_version_description(census_version)
   if (is.null(census)) {
@@ -60,6 +61,7 @@ get_source_h5ad_uri <- function(dataset_id, census_version = "stable", census =
 #' @export
 #'
 #' @examples
+#' download_source_h5ad("0895c838-e550-48a3-a777-dbcd35d30272", "/tmp/data.h5ad", overwrite = TRUE)
 download_source_h5ad <- function(dataset_id, file, overwrite = FALSE,
                                  census_version = "stable", census = NULL) {
   stopifnot("specify local filename, not directory" = !dir.exists(file))

api/r/cellxgene.census/_pkgdown.yml

@@ -4,3 +4,46 @@ template:
   includes:
     in_header: <script defer data-domain="chanzuckerberg.github.io/cellxgene-census" src="https://plausible.io/js/script.js"></script>
 
+home:
+  sidebar:
+    structure: [links, license, community, authors]
+
+navbar:
+  structure:
+    left: [docsite, reference, articles]
+  components:
+    docsite:
+      text: Main Census Site
+      href: https://chanzuckerberg.github.io/cellxgene-census/
+
+reference:
+- title: Open/retrieve Census data
+  contents:
+    - open_soma
+    - new_SOMATileDBContext_for_census
+    - download_source_h5ad
+    - get_source_h5ad_uri
+- title: Export slices of data
+  contents:
+    - get_seurat
+- title: Feature presence matrix
+  contents:
+    - get_presence_matrix
+- title: Versioning of Census builds
+  contents:
+    - get_census_version_description
+    - get_census_version_directory
+
+articles:
+- title: Analysis
+  navbar: "Explore anda analyze the data"
+  contents:
+    - comp_bio_census_info
+    - comp_bio_summarize_axis_query
+    - comp_bio_data_integration
+- title: API
+  navbar: "cellxgene.census capabilities"
+  contents:
+    - census_query_extract
+    - census_datasets
+    - census_dataset_presence