Skip to contents

make_gene_count

Source: R/star_solo_processing.R
make_gene_count.Rd

Constructs sparse gene expression matrices from one or more directories containing 10X Genomics-style output. The function supports barcode filtering using either an external whitelist or the internally provided filtered barcode file.

Usage

make_gene_count(
  expression_dirs,
  sample_ids,
  whitelist_barcodes = NULL,
  use_internal_whitelist = TRUE,
  verbose = FALSE,
  matrix_source = c("raw", "filtered", "auto"),
  matrix_file = "auto"
)

Arguments

expression_dirs

A character vector or list of strings. Each element must point to a gene-expression output directory containing raw and/or filtered subdirectories with the matrix, barcodes, and features files.

sample_ids

A character vector or list of unique sample identifiers, one for each element in expression_dirs. These are used to name outputs in the returned list when multiple samples are provided.

whitelist_barcodes

A list of character vectors. Each list element corresponds to a sample and contains the barcodes to retain for that sample. If NULL (default), the function will attempt to use the internal filtered barcode file (e.g., barcodes.tsv or barcodes_filtered.tsv) if available.

use_internal_whitelist

Logical (default TRUE). If TRUE and whitelist_barcodes is NULL, the function will attempt to use the default filtered barcode list from the input directory. If FALSE, no internal filtration will be applied unless a whitelist is explicitly provided.

verbose

Logical. If TRUE, prints progress and informational messages. Default is FALSE.

matrix_source

Character. Directory below each expression_dirs entry from which the count matrix, barcodes, and features are read. One of "raw", "filtered", or "auto". The default is "raw". The compatibility option "auto" preserves the historical directory behavior: it uses "filtered" when use_internal_whitelist = TRUE and "raw" otherwise.

matrix_file

Character. Name of the Matrix Market count file inside the selected source directory. The default, "auto", uses STARsolo's "UniqueAndMult-EM.mtx" when available and otherwise falls back to "matrix.mtx". Supply a filename explicitly to force that file.

Value

If a single sample is provided, returns a sparse matrix of class "dgCMatrix" with genes as rows and barcodes as columns. If multiple samples are provided, returns a named list of sparse matrices, one per sample ID.

Details

The function is designed for bulk or single-cell gene expression processing from 10X-style output folders. Each input directory should contain the standard matrix.mtx, features.tsv/genes.tsv, and barcodes.tsv files. Barcodes can be filtered using either a provided whitelist or by relying on the filtered barcode files output by tools like CellRanger.

If neither an external whitelist nor an internal filtered barcode file is available, all barcodes from the raw matrix will be retained.

Matrix selection and barcode filtering are independent. For example, matrix_source = "raw" with use_internal_whitelist = TRUE reads the raw count matrix and then retains barcodes listed in filtered/barcodes.tsv. In contrast, matrix_source = "filtered" reads the already-filtered matrix directly. With the defaults, raw/UniqueAndMult-EM.mtx is preferred and raw/matrix.mtx is used as a fallback.

Dependencies

Requires the Matrix package for sparse matrix handling and potentially data.table for efficient I/O.