Package 'cellNexus'

Description

cellNexus provides a query interface for programmatic exploration and retrieval of the harmonised, curated and reannotated CELLxGENE single-cell Human Cell Atlas. The package allows users to query metadata and download single-cell RNA sequencing data in various formats including SingleCellExperiment, Seurat, and pseudobulk SummarizedExperiment objects.

Value

The cellNexus package (invisibly).

Getting Started

To get started with cellNexus, first load the package and retrieve the metadata:

library(cellNexus)
metadata <- get_metadata()

Then filter the metadata to find cells of interest and download the data:

filtered_metadata <- metadata |>
    dplyr::filter(
        tissue == "lung parenchyma" &
        cell_type %LIKE% "%CD4%"
    )

sce <- get_single_cell_experiment(filtered_metadata)

Main Functions

get_metadata

Retrieve and query the harmonised metadata

get_single_cell_experiment

Download data as SingleCellExperiment objects

get_seurat

Download data as Seurat objects

get_pseudobulk

Download aggregated pseudobulk data

Data Licensing

Important: The Human Cell Atlas data accessed through this package is subject to its own licensing terms, which differ from the package license. The cellNexus package itself is licensed under GPL-3. However, the underlying Human Cell Atlas data is typically licensed under Creative Commons Attribution (CC-BY) or similar open data licenses as specified by the Human Cell Atlas Data Use Agreement. Users should review the specific licensing terms for any datasets they access through this package. For more information, see the Human Cell Atlas Data Portal: https://data.humancellatlas.org/about

Vignettes

See vignette("cellNexus", package = "cellNexus") for a comprehensive introduction to using the package.

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Description

Create a Shiny app that allows users to generate filtering & retreival code for cellNexus

Usage

create_interface_app(ui_choices, return_as_list = FALSE)

Arguments

Value

A Shiny app that allows users to filter cellNexus metadata and generate code for retrieval in the selected format.

Author(s)

Jared Andrews

Source

Mangiola et al.,2023

Examples

get_default_cache_dir()

# Create the interface app with metadata
metadata <- get_metadata(cloud_metadata = SAMPLE_DATABASE_URL)
app <- create_interface_app(metadata)
# Run the app
shiny::runApp(app)

Description

Downloads the atlas_versions.parquet registry from the cellNexus metadata store, caches it locally, and returns it as an in-memory tibble. Each row describes one atlas data release and its relationship to a CellxGene Census snapshot.

Usage

get_atlas_versions(cache = tempdir())

Arguments

Details

The atlas_id column in this table corresponds directly to the atlas_id column returned by get_metadata(), so you can join them to find which Census snapshot any cell in your query came from.

Value

A tibble with columns:

atlas_id

Atlas version identifier, e.g. "cellxgene_2024/0.1.0". Matches the atlas_id column in get_metadata().

census_version

The CellxGene Census snapshot this atlas was built from, e.g. "01-07-2024".

change_type

One of "initial", "patch", "minor", or "major". See ATLAS_VERSIONS.md for the conventions standards.

description

Summary text of what changed in this release.

modified_at

Modification date as a character scalar ("YYYY-MM-DD"). By default use Sys.Date()

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

See Also

• CellxGene Census data releases (LTS): https://chanzuckerberg.github.io/cellxgene-census/cellxgene_census_docsite_data_release_info.html

Examples

get_atlas_versions()

Description

Downloads a parquet database of the cell communication strength to a local cache, and then opens it as a data frame. It can then be filtered.

Usage

get_cell_communication_strength(
  cloud_metadata =
    get_metadata_url("cellNexus_lr_signaling_pathway_strength_DEMO.parquet"),
  local_metadata = NULL,
  cache_directory = get_default_cache_dir(),
  use_cache = TRUE
)

Arguments

Details

The returned table integrates three levels of cell communication inference from CellChat, for each sample: (i) ligand–receptor–level communication (lr_prob, lr_pval), (ii) pathway-level aggregated signaling (pathway_prob, pathway_pval), (iii) cell-pair–level summaries of communication breadth (interaction_count - number of significant LR interactions) and intensity (interaction_weight - overall communication strength).

Together, these metrics allow simultaneous assessment of signaling specificity, pathway dominance, and global communication structure between cell populations.

Value

A lazy data.frame subclass containing the metadata. You can interact with this object using most standard dplyr functions. For string matching, it is recommended that you use stringr::str_like to filter character columns, as stringr::str_match will not work.

Examples

# For fast build purpose only, you do not need to specify anything in the function.
communication_meta <- get_cell_communication_strength(
  cloud_metadata = get_metadata_url(
    "cellNexus_lr_signaling_pathway_strength_DEMO.parquet"
  )
)

Description

Generating counts per million from a SingleCellExperiment object

Usage

get_counts_per_million(sce, output_file)

Arguments

Value

A directory stores counts per million Anndata

Examples

data(pbmc3k_sce)
get_counts_per_million(pbmc3k_sce, tempfile(fileext = ".h5ad"))

Description

Returns the default cache directory with a version number

Usage

get_default_cache_dir()

Value

A length one character vector.

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

get_metadata(cloud_metadata = SAMPLE_DATABASE_URL, cache_directory = get_default_cache_dir())

Description

Downloads a parquet database of the Human Cell Atlas metadata to a local cache, and then opens it as a data frame. It can then be filtered and passed into get_single_cell_experiment() to obtain a SingleCellExperiment::SingleCellExperiment

Usage

get_metadata(
  cloud_metadata = get_metadata_url("cellnexus_metadata.2.3.0.parquet"),
  local_metadata = NULL,
  cache_directory = get_default_cache_dir(),
  use_cache = TRUE
)

Arguments

Details

The metadata was collected from the Bioconductor package cellxgenedp. vignette("using_cellxgenedp", package="cellxgenedp") provides an overview of the columns in the metadata. The data for which the column organism_name included "Homo sapiens" was collected collected from cellxgenedp.

The columns dataset_id and file_id_cellNexus_single_cell link the datasets explorable through cellNexus and cellxgenedpto the CELLxGENE portal.

Our representation, harmonises the metadata at dataset, sample and cell levels, in a unique coherent database table.

Field definitions for the CELLxGENE schema follow the CELLxGENE schema 5.1.0.

Through harmonisation and curation we introduced custom columns not present in the original CELLxGENE metadata:

cell_count: Number of cells in a dataset. feature_count: Number of genes in a dataset. age_days: Donor age in days. tissue_groups: Coarse tissue grouping for analysis. empty_droplet: Whether a cell is called an empty droplet from expressed-gene count per sample (default threshold 200; targeted panels may differ). alive: Whether a cell passes viability / mitochondrial QC. scDblFinder.class: Doublet, singlet, or unknown (scDblFinder default parameters). cell_type_unified_ensemble: Consensus immune identity from Azimuth and SingleR (Blueprint, Monaco). cell_annotation_azimuth_l2: Azimuth cell annotation. cell_annotation_blueprint_singler: SingleR annotation (Blueprint). cell_annotation_blueprint_monaco: SingleR annotation (Monaco). is_immune: Whether a cell is an immune cell. sample_heuristic: Internal sample subdivision helper. file_id_cellNexus_single_cell: Internal file id for single-cell layers. file_id_cellNexus_pseudobulk: Internal file id for pseudobulk layers. sample_id: Harmonised sample identifier. nCount_RNA: Total RNA counts per cell (sample-aware). nFeature_expressed_in_sample: Number of expressed features per cell. ethnicity_flagging_score: Supporting score for ethnicity imputation. low_confidence_ethnicity: Supporting flag for low-confidence ethnicity calls. .aggregated_cells: Post-QC cells combined into each pseudobulk sample. imputed_ethnicity: Imputed ethnicity label. atlas_id: cellNexus atlas release identifier (internal use).

For all fields definitions, please refer to our documentation site

Possible cache path issues

If your default R cache path includes non-standard characters (e.g. dash because of your user or organisation name), the following error can occur.

Error in `db_query_fields.DBIConnection()`: ! Can't query fields. Caused by
error: ! Parser Error: syntax error at or near "/" LINE 2: FROM
/Users/bob/Library/Caches...

The solution is to choose a different cache, for example

get_metadata(cache_directory = path.expand('~'))

Value

A lazy data.frame subclass containing the metadata. You can interact with this object using most standard dplyr functions. For string matching, it is recommended that you use stringr::str_like to filter character columns, as stringr::str_match will not work.

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

library(dplyr)
# For fast build purpose only, you do not need to specify anything in cloud_metadata.
filtered_metadata <- get_metadata(cloud_metadata = SAMPLE_DATABASE_URL) |>
  filter(
    self_reported_ethnicity == "African" &
      assay %LIKE% "%10x%" &
      tissue == "lung parenchyma" &
      cell_type %LIKE% "%CD4%"
  )

Description

Returns the URLs for all metadata files

Usage

get_metadata_url(
  databases = c("cellnexus_metadata.2.3.0.parquet", "census_cell_metadata.2.3.0.parquet")
)

Arguments

Value

A character vector of URLs to parquet files to download

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

get_metadata_url("cellnexus_metadata.2.3.0.parquet")

Description

Given a data frame of Curated Atlas metadata obtained from get_metadata(), returns a SummarizedExperiment::SummarizedExperiment object corresponding to the samples in that data frame

Usage

get_pseudobulk(
  data,
  assays = "counts",
  cell_aggregation = "pseudobulk",
  cache_directory = get_default_cache_dir(),
  repository = COUNTS_URL,
  features = NULL,
  as_SummarizedExperiment = FALSE
)

Arguments

Value

By default, a SingleCellExperiment object. If as_SummarizedExperiment is TRUE, a SummarizedExperiment object.

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

# Use the lightweight sample database URL (for fast checks during development only)
meta <- get_metadata(cloud_metadata = cellNexus::SAMPLE_DATABASE_URL) |>
  keep_quality_cells() |>
  dplyr::filter(cell_type_unified_ensemble == "epithelial")
pseudobulk <- meta |> get_pseudobulk()

Description

Given a data frame of HCA metadata, returns a Seurat object corresponding to the samples in that data frame

Usage

get_seurat(...)

Arguments

Value

A Seurat object containing the same data as a call to get_single_cell_experiment()

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

# Use the lightweight sample database URL (for fast checks during development only)
meta <- get_metadata(cloud_metadata = cellNexus::SAMPLE_DATABASE_URL) |> head(2)
seurat <- get_seurat(meta)

Description

Given a data frame of Curated Atlas metadata obtained from get_metadata(), returns a SingleCellExperiment::SingleCellExperiment object corresponding to the samples in that data frame

Usage

get_single_cell_experiment(
  data,
  assays = "counts",
  cell_aggregation = "",
  cache_directory = get_default_cache_dir(),
  repository = COUNTS_URL,
  features = NULL
)

Arguments

Value

A SingleCellExperiment object.

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

# Use the lightweight sample database URL (for fast checks during development only)
meta <- get_metadata(cloud_metadata = cellNexus::SAMPLE_DATABASE_URL) |> head(2)
sce <- get_single_cell_experiment(meta)

Description

Given a data frame of Curated Atlas metadata obtained from get_metadata(), returns a SingleCellExperiment::SingleCellExperiment object corresponding to the samples in that data frame

Usage

get_SingleCellExperiment(...)

Arguments

Value

A SingleCellExperiment object.

Source

Mangiola et al., 2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

# Use the lightweight sample database URL (for fast checks during development only)
meta <- get_metadata(cloud_metadata = cellNexus::SAMPLE_DATABASE_URL) |> head(2)
sce <- get_single_cell_experiment(meta)

Description

Downloads and joins the Census metadata with cellNexus metadata. This function creates indexed tables for efficient joining and returns a data frame.

Usage

join_census_table(
  tbl,
  cloud_metadata = get_metadata_url("census_cell_metadata.2.3.0.parquet"),
  cache_directory = get_default_cache_dir(),
  join_keys = c("sample_id", "dataset_id", "observation_joinid")
)

Arguments

Value

A lazy SQL table with Census metadata joined to the cellNexus metadata.

Examples

library(dplyr)
get_metadata(cloud_metadata = SAMPLE_DATABASE_URL) |> head(2) |>
  # You do not need to specify anything in cloud_metadata
  join_census_table(
    cloud_metadata = SAMPLE_DATABASE_URL,
    cache_directory = tempdir()
  )

Description

Keep high-quality cells based on QC columns

Usage

keep_quality_cells(
  data,
  empty_droplet_col = "empty_droplet",
  alive_col = "alive",
  doublet_col = "scDblFinder.class"
)

Arguments

Value

A filtered data frame containing only cells that pass all QC checks.

Source

Mangiola et al.,2023

Examples

get_metadata(cloud_metadata = SAMPLE_DATABASE_URL, cache_directory = tempdir()) |>
  head(2) |>
  keep_quality_cells()

Description

Organize arbitrary Shiny inputs into a grid layout

Usage

organize_inputs(
  tag.list,
  id = NULL,
  title = NULL,
  tack = NULL,
  columns = NULL,
  rows = NULL
)

Arguments

Value

A Shiny tagList with inputs organized into a grid, optionally nested inside a tabsetPanel.

Author(s)

Jared Andrews

Source

Mangiola et al.,2023

Examples

library(shiny)
# Example 1: Basic usage with a simple grid
ui.inputs <- tagList(
  textInput("name", "Name"),
  numericInput("age", "Age", value = 30),
  selectInput("gender", "Gender", choices = c("Male", "Female", "Other"))
)
organize_inputs(ui.inputs, columns = 2, rows = 2)

# Example 2: Using a named list to create tabs
ui.inputs.tabs <- list(
  Personal = tagList(
    textInput("firstname", "First Name"),
    textInput("lastname", "Last Name")
  ),
  Settings = tagList(
    checkboxInput("newsletter", "Subscribe to newsletter", value = TRUE),
    sliderInput("volume", "Volume", min = 0, max = 100, value = 50)
  )
)
organize_inputs(ui.inputs.tabs, columns = 2)

# Example 3: Adding an additional UI element with 'tack'
additional.ui <- actionButton("submit", "Submit")
organize_inputs(ui.inputs, tack = additional.ui, columns = 3)

# Example 4: Handling a case with more inputs than grid cells
many.inputs <- tagList(replicate(10, textInput("input", "Input")))
organize_inputs(many.inputs, columns = 3) # Creates more than one row

Description

A sample SingleCellExperiment object created from the pbmc3k dataset for testing and demonstration purposes. The dataset contains 500 cells with gene expression data mapped to Ensembl gene IDs and formatted with cellNexus-compatible metadata structure.

Format

An object of class SingleCellExperiment with:

assays

Gene expression matrix with Ensembl gene IDs as rownames

colData

Cell metadata including sample_id, cell_type_unified_ensemble, nCount_RNA, etc.

metadata

List containing 'data' field with cellNexus-formatted metadata including:

• cell_id: Unique cell identifier

• sample_id: Sample identifier

• cell_type_unified_ensemble: Cell type annotation

• nCount_RNA: Number of RNA molecules per cell

• ident: Seurat cluster identity

• dataset_id: Dataset identifier

• file_id_cellNexus_single_cell: Generated file ID for cellNexus

• atlas_id: Atlas identifier with date

Details

See dev/create_pbmc3k_sce.R for the complete creation script.

Source

Created from pbmc3k dataset (SeuratData package)

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

data(pbmc3k_sce)
pbmc3k_sce
# Access metadata
S4Vectors::metadata(pbmc3k_sce)$data

Description

URL pointing to the sample metadata file, which is smaller and for test, demonstration, and vignette purposes only

Usage

SAMPLE_DATABASE_URL

Format

An object of class character of length 2.

Value

Character scalar consisting of the URL/URLs

Source

Mangiola et al.,2023

References

Mangiola, S., M. Milton, N. Ranathunga, C. S. N. Li-Wai-Suen, A. Odainic, E. Yang, W. Hutchison et al. "A multi-organ map of the human immune system across age, sex and ethnicity." bioRxiv (2023): 2023-06. doi:10.1101/2023.06.08.542671.

Examples

get_metadata(cloud_metadata = SAMPLE_DATABASE_URL["cellnexus"], cache_directory = tempdir())

Description

A list of unique values for each filterable column used in the cellNexus Shiny interface app. Pre-computing these choices avoids slow metadata queries when the app starts.

Usage

data(ui_choices)

Format

A named list where each element contains unique values for a column:

cell_type_unified_ensemble

Character vector of unified cell type labels

cell_type

Character vector of original cell type labels

alive

Logical values for cell viability

scDblFinder.class

Character vector of doublet classification results

is_immune

Logical values for immune cell classification

empty_droplet

Logical values for empty droplet detection

development_stage

Character vector of developmental stages

disease

Character vector of disease states

self_reported_ethnicity

Character vector of ethnicity labels

sex

Character vector of sex labels

tissue

Character vector of tissue types

tissue_groups

Character vector of tissue group labels

Details

See dev/generate_ui_choices.R for the creation script. Run this script to regenerate the choices when metadata columns change.

Source

Generated from cellNexus metadata