Package 'nemoR'

Description

Returns values from file.file_access. Use access = "open" in search and fetch workflows when you want files that can be downloaded without controlled-access authorization.

Usage

nemo_access_types(...)

Arguments

Value

A tibble of access categories and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_access_types(file_format = "h5ad")

## End(Not run)

Description

Dispatches from manifest file paths to the supported reader for the first compatible file. H5AD files are preferred over 10x HDF5 files when both are present. NeMO provenance from the manifest is attached to the returned object when S4Vectors is available.

Usage

nemo_as_sce(manifest, ...)

Arguments

Value

A SingleCellExperiment object.

Examples

# Loading a single-cell dataset requires local downloaded .h5ad or
# 10x .h5 files, so this code is not run in examples.
## Not run: 
downloaded <- nemo_read_manifest("nemo_downloads/nemo_manifest.tsv")
sce <- nemo_as_sce(downloaded)

## End(Not run)

Description

Thin wrapper around Seurat::as.Seurat() used by nemo_load() when format = "Seurat". Seurat is optional and must be installed separately.

Usage

nemo_as_seurat(object)

Arguments

Value

A Seurat object.

Examples

# Requires optional Seurat conversion and is not run in examples.
## Not run: 
if (requireNamespace("SingleCellExperiment", quietly = TRUE) &&
    requireNamespace("Seurat", quietly = TRUE) &&
    requireNamespace("Matrix", quietly = TRUE)) {
  mat <- Matrix::Matrix(c(1, 0, 2, 0, 3, 0), nrow = 3, sparse = TRUE)
  rownames(mat) <- paste0("gene", seq_len(nrow(mat)))
  colnames(mat) <- paste0("cell", seq_len(ncol(mat)))
  sce <- SingleCellExperiment::SingleCellExperiment(
    list(counts = mat, logcounts = mat)
  )
  seurat_obj <- nemo_as_seurat(sce)
  dim(seurat_obj)
}

## End(Not run)

Description

Returns values from sample.assay, optionally filtered by organism, technique, modality, file format, or other search arguments.

Usage

nemo_assays(...)

Arguments

Value

A tibble of assays and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_assays(taxon = "house mouse")

## End(Not run)

Description

Returns values from sample.anatomies, which can be used as the anatomy or brain_region filter in search and fetch functions.

Usage

nemo_brain_regions(...)

Arguments

Value

A tibble of anatomical regions and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_brain_regions(taxon = "house mouse")

## End(Not run)

Description

Returns the default directory used by nemo_download() when destdir is not supplied. The location can be overridden with the NEMOR_CACHE_DIR environment variable.

Usage

nemo_cache_dir()

Value

Path to the cache directory. The directory is created if needed.

Examples

nemo_cache_dir()

Description

Retrieves one collection record from the NeMO Assets API by collection identifier. Use nemo_files() to list file records attached to a collection.

Usage

nemo_collection(id)

Arguments

Value

Parsed collection metadata from the Assets API.

Examples

# Queries the external NeMO Assets API; not run during package checks.
## Not run: 
nemo_collection("nemo:col-rmf5gdy")

## End(Not run)

Description

The public NeMO Assets API is currently identifier-based. This helper returns documented example public collections that are useful for API tests and demonstrations. It is not intended to be a complete collection catalog.

Usage

nemo_collections(...)

Arguments

Value

A tibble with name, collection_id, and api_url columns.

Examples

nemo_collections()

Description

Returns values from file.data_type, such as processed counts, parameters, raw data, or analysis outputs, depending on what NeMO records match the filters.

Usage

nemo_data_types(...)

Arguments

Value

A tibble of file data types and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_data_types(taxon = "house mouse", file_format = "h5ad")

## End(Not run)

Description

Downloads each row of a NeMO manifest to a local folder and returns the same manifest with local_path, download_status, and checksum_verified updated. Existing files are skipped unless overwrite = TRUE. NeMO datasets can contain large raw or processed files. Use nemo_download_plan() and the max_size_gb guard before downloading, and increase max_size_gb only when the transfer is intentional.

Usage

nemo_download(
  manifest,
  destdir = nemo_cache_dir(),
  overwrite = FALSE,
  max_size_gb = 2,
  verify_checksum = FALSE,
  quiet = FALSE
)

Arguments

Value

Updated manifest tibble. download_status is set to values such as "downloaded", "skipped_existing", "failed", or "failed_missing_url". checksum_verified is TRUE, FALSE, or NA.

Examples

source_file <- tempfile()
writeLines("small local file", source_file)
manifest <- nemo_manifest_from_urls(
  paste0("file://", normalizePath(source_file)),
  collection_id = "local-example"
)
manifest$size <- file.info(source_file)$size
nemo_download_plan(manifest, max_size_gb = 1)

# Downloads write files to disk and may transfer large external data.
## Not run: 
destdir <- tempfile()
dir.create(destdir)
downloaded <- nemo_download(manifest, destdir = destdir, quiet = TRUE)
downloaded[, c("file_name", "download_status", "local_path")]

## End(Not run)

Description

Use this before downloading to check how many files will be downloaded and how large they are. The summary includes file formats, data types, known total size, whether the size guard would pass, and how many rows have checksums available.

Usage

nemo_download_plan(manifest, max_size_gb = 2)

Arguments

Value

A one-row tibble with columns n_files, total_size_gb, largest_file_gb, unknown_size_files, within_size_limit, file_formats, data_types, access, download_statuses, and files_with_checksum.

Examples

manifest <- nemo_manifest_from_urls(
  "https://example.com?file=sample.h5ad",
  collection_id = "example"
)
manifest$size <- 1024^2
nemo_download_plan(manifest, max_size_gb = 1)
nemo_download_plan(manifest, max_size_gb = 0.0001)

Description

These identifiers are small, stable examples useful for documentation, smoke tests, and learning the identifier-based Assets API. They are not a complete catalog of NeMO collections; use the portal search functions for broad discovery.

Usage

nemo_example_collections()

Value

A named character vector of public collection identifiers from the NeMO Assets API documentation.

Examples

nemo_example_collections()

Description

This is the general discovery helper behind convenience functions such as nemo_species() and nemo_platforms(). It asks the NeMO Data Portal for aggregation buckets, so it is useful for learning valid filter values before running nemo_search() or nemo_fetch().

Usage

nemo_facet_values(
  facets,
  target = c("files", "samples"),
  organism = NULL,
  taxon = NULL,
  species = NULL,
  technique = NULL,
  modality = NULL,
  assay = NULL,
  brain_region = NULL,
  anatomy = NULL,
  specimen_type = NULL,
  study = NULL,
  project = NULL,
  program = NULL,
  lab = NULL,
  file_format = NULL,
  data_type = NULL,
  access = NULL,
  filters = NULL,
  size = 1
)

Arguments

Value

A tibble with facet, value, and count columns. value is a usable filter value and count is the number of matching portal records in the requested target.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_facet_values("subject.taxon")
nemo_facet_values("file.format", taxon = "house mouse", access = "open")

## End(Not run)

Description

nemo_fetch() is the highest-level data fetching helper. It searches the NeMO Data Portal, builds a manifest, checks the planned download size, and downloads files to a selected folder. Use dry_run = TRUE to inspect the matching files and attached download plan without downloading anything. Downloading real NeMO files can transfer large external datasets, so examples that perform downloads are wrapped in ⁠\dontrun{}⁠. Inspect a dry run and adjust max_size_gb before starting a download.

Usage

nemo_fetch(
  destdir,
  organism = NULL,
  taxon = NULL,
  species = NULL,
  technique = NULL,
  modality = NULL,
  assay = NULL,
  brain_region = NULL,
  anatomy = NULL,
  specimen_type = NULL,
  study = NULL,
  project = NULL,
  program = NULL,
  lab = NULL,
  file_format = NULL,
  data_type = NULL,
  access = "open",
  file_name = NULL,
  file_id = NULL,
  sample_id = NULL,
  filters = NULL,
  max_files = 100,
  max_size_gb = 2,
  overwrite = FALSE,
  verify_checksum = FALSE,
  quiet = FALSE,
  dry_run = FALSE,
  save_manifest = TRUE,
  manifest_name = "nemo_manifest.tsv",
  ...
)

Arguments

Value

A manifest tibble. For downloads, local_path, download_status, and checksum_verified describe local file state. For dry runs, download_status is "dry_run" and the planned summary is stored in the "download_plan" attribute.

Examples

# Searches external NeMO services; not run during package checks.
## Not run: 
preview <- nemo_fetch(
  destdir = tempdir(),
  taxon = "house mouse",
  file_format = "h5ad",
  access = "open",
  max_files = 1,
  dry_run = TRUE
)
attr(preview, "download_plan")

# Downloads real external data; inspect the dry-run plan first.
manifest <- nemo_fetch(
  destdir = "nemo_downloads",
  taxon = "house mouse",
  file_format = "h5ad",
  access = "open",
  max_files = 1,
  max_size_gb = 2
)

## End(Not run)

Description

Retrieves one file record from the NeMO Assets API. The response can include file format, size, checksum, access level, collection membership, and available manifest URLs.

Usage

nemo_file(id)

Arguments

Value

Parsed file metadata from the Assets API.

Examples

# Queries the external NeMO Assets API; not run during package checks.
## Not run: 
nemo_file("nemo:fil-328dskg")

## End(Not run)

Description

Returns values from file.format, such as "h5ad", "h5", "fastq", "bam", "json", "csv", or "mtx", depending on the current filters.

Usage

nemo_file_formats(...)

Arguments

Value

A tibble of file formats and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_file_formats(taxon = "house mouse", access = "open")

## End(Not run)

Description

Uses the NeMO Assets API to list file records for a known collection ID. For broad discovery by species, assay, file type, or access level, use nemo_search(target = "files") or nemo_search_manifest().

Usage

nemo_files(collection_id, page = 1, page_size = 100, ...)

Arguments

Value

A tibble of file metadata returned by the Assets API.

Examples

# Queries the external NeMO Assets API; not run during package checks.
## Not run: 
nemo_files("nemo:col-rmf5gdy", page_size = 2)

## End(Not run)

Description

Returns values from study.labs, optionally narrowed by species, technique, modality, file format, or other filters.

Usage

nemo_labs(...)

Arguments

Value

A tibble of labs and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_labs(taxon = "house mouse")

## End(Not run)

Description

Uses the local file paths recorded in a NeMO manifest to create a SingleCellExperiment or Seurat object. This function assumes the files have already been downloaded and currently supports the first compatible .h5ad or 10x .h5 file in the manifest.

Usage

nemo_load(manifest, format = c("SingleCellExperiment", "Seurat"), ...)

Arguments

Value

A SingleCellExperiment object by default, or a Seurat object when format = "Seurat".

Examples

# Loading a single-cell dataset requires local downloaded .h5ad or
# 10x .h5 files, so this code is not run in examples.
## Not run: 
downloaded <- nemo_read_manifest("nemo_downloads/nemo_manifest.tsv")
sce <- nemo_load(downloaded)

## End(Not run)

Description

Builds a manifest from a known NeMO collection and its Assets API file records. A manifest is the package's reproducibility table: it records file identifiers, names, formats, sizes, checksums, download URLs, local paths, query provenance, and download status.

Usage

nemo_manifest(
  collection_id,
  files = NULL,
  pattern = NULL,
  file_format = NULL,
  data_type = NULL,
  max_files = NULL
)

Arguments

Value

A manifest tibble suitable for nemo_download() and nemo_write_manifest().

Examples

files <- data.frame(
  file_id = "file-1",
  file_name = "sample.h5ad",
  file_format = "h5ad",
  data_type = "counts",
  size = 1024,
  md5 = "abc",
  download_url = "https://example.com?file=sample.h5ad"
)
nemo_manifest("example-collection", files = files)

Description

Use this for public files discovered through the NeMO HTTP browser, such as processed .h5ad files, when an Assets API collection is not yet known.

Usage

nemo_manifest_from_urls(urls, collection_id = "direct-url", file_id = NULL)

Arguments

Value

A manifest tibble with one row per URL.

Examples

manifest <- nemo_manifest_from_urls(
  "https://example.com?file=sample.h5ad",
  collection_id = "example"
)
manifest

Description

Returns values from sample.modality, such as transcriptomic or epigenomic measurement categories, optionally filtered by organism, technique, file type, or other search arguments.

Usage

nemo_modalities(...)

Arguments

Value

A tibble of modalities and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_modalities(taxon = "house mouse", access = "open")

## End(Not run)

Description

In NeMO portal metadata, platform-like values are represented by sample.technique, for example "10x chromium 3' v2 sequencing".

Usage

nemo_platforms(...)

Arguments

Value

A tibble of techniques/platforms and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_platforms(taxon = "house mouse")

## End(Not run)

Description

Retrieves one project record from the NeMO Assets API by project identifier. This is a low-level wrapper for users who already know the NeMO project ID.

Usage

nemo_project(id)

Arguments

Value

Parsed project metadata from the Assets API.

Examples

# Queries the external NeMO Assets API; not run during package checks.
## Not run: 
nemo_project("nemo:proj-example")

## End(Not run)

Description

Reads a 10x-style .h5 count file and returns the object produced by DropletUtils::read10xCounts(). This is intended for processed count matrices rather than raw sequencing reads.

Usage

nemo_read_10x_h5(path, ...)

Arguments

Value

A SingleCellExperiment object.

Examples

# Requires a local 10x HDF5 single-cell file; not run in examples.
## Not run: 
sce <- nemo_read_10x_h5("nemo_downloads/sample_10x.h5")

## End(Not run)

Description

Reads an .h5ad file downloaded from NeMO or supplied manually and returns the object produced by zellkonverter::readH5AD(). This function does not search or download data; use nemo_fetch() or nemo_download() first.

Usage

nemo_read_h5ad(path, ...)

Arguments

Value

A SingleCellExperiment object.

Examples

# Requires a local H5AD file, typically after running nemo_download().
## Not run: 
sce <- nemo_read_h5ad("nemo_downloads/sample.h5ad")

## End(Not run)

Description

Reads a manifest previously written by nemo_write_manifest().

Usage

nemo_read_manifest(path)

Arguments

Value

Manifest tibble.

Examples

manifest <- nemo_manifest_from_urls("https://example.com?file=sample.h5ad")
path <- tempfile(fileext = ".tsv")
nemo_write_manifest(manifest, path)
nemo_read_manifest(path)

Description

Finds matrix.mtx or matrix.mtx.gz in a directory and reads it with Matrix::readMM(). This first-pass reader currently returns only the sparse matrix; barcode and feature annotation files are not yet attached.

Usage

nemo_read_mtx(path)

Arguments

Value

A sparse matrix read from the Matrix Market file.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {
  dir <- tempfile()
  dir.create(dir)
  mat <- Matrix::Matrix(c(1, 0, 2, 0), nrow = 2, sparse = TRUE)
  Matrix::writeMM(mat, file.path(dir, "matrix.mtx"))
  nemo_read_mtx(dir)
}

Description

This function uses the NeMO Data Portal API for faceted metadata discovery. Use target = "files" to find downloadable files, target = "samples" to find biospecimen/library records, and target = "projects" to summarize studies/grants. Routine users can use biological argument names such as taxon, technique, and brain_region rather than internal portal field names.

Usage

nemo_search(
  organism = NULL,
  taxon = NULL,
  species = NULL,
  technique = NULL,
  modality = NULL,
  assay = NULL,
  brain_region = NULL,
  anatomy = NULL,
  specimen_type = NULL,
  study = NULL,
  project = NULL,
  program = NULL,
  lab = NULL,
  file_format = NULL,
  data_type = NULL,
  access = NULL,
  file_name = NULL,
  file_id = NULL,
  sample_id = NULL,
  target = c("files", "samples", "projects"),
  fields = NULL,
  facets = NULL,
  filters = NULL,
  size = 100,
  from = 0,
  sort = NULL,
  ...
)

Arguments

Value

A tibble of matching portal records. Column names are portal field names such as file.file_id, file.name, or subject.taxon. Pagination metadata is stored in the "pagination" attribute and aggregation metadata in the "aggregations" attribute when requested.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
results <- nemo_search(
  taxon = "house mouse",
  file_format = "h5ad",
  access = "open",
  target = "files",
  size = 1
)
results
attr(results, "pagination")

## End(Not run)

Description

Retrieves field metadata from the NeMO portal mapping endpoint. This is most useful when constructing advanced fields, facets, or raw filters arguments.

Usage

nemo_search_fields(target = NULL)

Arguments

Value

A tibble of portal fields and metadata returned by the mapping endpoint.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_search_fields("files")

## End(Not run)

Description

This function connects discovery to download. It searches the NeMO Data Portal for file records, enriches those file IDs through the NeMO Assets API, and returns a manifest that can be passed to nemo_download(). It is usually the best entry point when you want a reproducible list of open NeMO files before downloading them.

Usage

nemo_search_manifest(
  organism = NULL,
  taxon = NULL,
  species = NULL,
  technique = NULL,
  modality = NULL,
  assay = NULL,
  brain_region = NULL,
  anatomy = NULL,
  specimen_type = NULL,
  study = NULL,
  project = NULL,
  program = NULL,
  lab = NULL,
  file_format = NULL,
  data_type = NULL,
  access = "open",
  file_name = NULL,
  file_id = NULL,
  sample_id = NULL,
  filters = NULL,
  max_files = 100,
  enrich = TRUE,
  require_download_url = TRUE,
  sort = "file.file_id:asc",
  ...
)

Arguments

Value

A tibble manifest suitable for nemo_download(). The manifest includes search metadata such as taxon, technique, study, query_parameters, retrieved_at, and download fields such as download_url, download_status, and checksum_verified.

Examples

# Queries external NeMO services; not run during package checks.
## Not run: 
manifest <- nemo_search_manifest(
  taxon = "house mouse",
  file_format = "h5ad",
  access = "open",
  max_files = 1
)
manifest

## End(Not run)

Description

Returns values from the portal field subject.taxon, such as "house mouse" or "human", optionally after applying filters passed through ....

Usage

nemo_species(...)

Arguments

Value

A tibble of species/taxa and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_species()
nemo_species(file_format = "h5ad", access = "open")

## End(Not run)

Description

Returns values from study.study_name, optionally narrowed by species, technique, modality, file format, or other filters.

Usage

nemo_studies(...)

Arguments

Value

A tibble of study names and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_studies(taxon = "house mouse")

## End(Not run)

Description

Alias for nemo_species().

Usage

nemo_taxa(...)

Arguments

Value

A tibble of taxa and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_taxa()

## End(Not run)

Description

Alias for nemo_platforms().

Usage

nemo_techniques(...)

Arguments

Value

A tibble of techniques and counts.

Examples

# Queries the external NeMO Data Portal; not run during package checks.
## Not run: 
nemo_techniques(taxon = "house mouse")

## End(Not run)

Description

Checks that a table has the minimum columns needed by the download and load workflow. This validates structure only; it does not check that URLs are reachable or local files exist.

Usage

nemo_validate_manifest(manifest)

Arguments

Value

Invisibly returns manifest.

Examples

manifest <- nemo_manifest_from_urls("https://example.com?file=sample.h5ad")
nemo_validate_manifest(manifest)

Description

Writes a manifest to a tab-separated file for reproducibility. Saved manifests can be restored with nemo_read_manifest() and passed back to nemo_download() or loading helpers.

Usage

nemo_write_manifest(manifest, path)

Arguments

Value

Invisibly returns path.

Examples

manifest <- nemo_manifest_from_urls("https://example.com?file=sample.h5ad")
path <- tempfile(fileext = ".tsv")
nemo_write_manifest(manifest, path)