Skip to main content

SingleCellReading

bixverse_sc_data::data_io

Trait SingleCellReading 

Source 
pub trait SingleCellReading: Send + Sync {

Show 19 methods    // Required methods
    fn read_cells_parallel(
        &self,
        indices: &[usize],
    ) -> Result<Vec<CsrCellChunk>, ScDataErrors>;
    fn read_gene_parallel(
        &self,
        indices: &[usize],
    ) -> Result<Vec<CscGeneChunk>, ScDataErrors>;
    fn read_cells_sparse<T>(
        &self,
        indices: &[usize],
        data_layer: &DataLayerReturn,
    ) -> Result<CompressedSparseData2<T, f32>, ScDataErrors>
       where T: BixverseNumeric + FromPrimitive;
    fn read_genes_sparse<T>(
        &self,
        indices: &[usize],
        cells_to_keep: Option<&IndexSet<u32>>,
        data_layer: &DataLayerReturn,
    ) -> Result<CompressedSparseData2<T, f32>, ScDataErrors>
       where T: BixverseNumeric + FromPrimitive;
    fn get_header(&self) -> SparseDataHeader;
    fn is_cell_based(&self) -> bool;

    // Provided methods
    fn read_gene_parallel_raw(
        &self,
        indices: &[usize],
    ) -> Result<Vec<CscGeneChunk>, ScDataErrors> { ... }
    fn is_gene_based(&self) -> bool { ... }
    fn target_size(&self) -> Option<f32> { ... }
    fn read_cell(&self, index: usize) -> Result<CsrCellChunk, ScDataErrors> { ... }
    fn read_gene(&self, index: usize) -> Result<CscGeneChunk, ScDataErrors> { ... }
    fn read_cells_range(
        &self,
        start: usize,
        end: usize,
    ) -> Result<Vec<CsrCellChunk>, ScDataErrors> { ... }
    fn get_all_cells(&self) -> Result<Vec<CsrCellChunk>, ScDataErrors> { ... }
    fn get_all_genes(&self) -> Result<Vec<CscGeneChunk>, ScDataErrors> { ... }
    fn read_gene_parallel_filtered(
        &self,
        indices: &[usize],
        cells_to_keep: &IndexSet<u32>,
    ) -> Result<Vec<CscGeneChunk>, ScDataErrors> { ... }
    fn read_cell_library_sizes(
        &self,
        indices: &[usize],
    ) -> Result<Vec<usize>, ScDataErrors> { ... }
    fn read_gene_nnz(
        &self,
        indices: &[usize],
    ) -> Result<Vec<usize>, ScDataErrors> { ... }
    fn get_all_gene_nnz(&self) -> Result<Vec<usize>, ScDataErrors> { ... }
    fn get_clr_offsets(
        &self,
        indices: &[usize],
        batch_size: Option<usize>,
    ) -> Result<Vec<f64>, ScDataErrors> { ... }

}
Expand description

Read access to a chunked single cell count store.

Abstracts over where the data physically lives. The only implementor today is ParallelSparseReader, which memory-maps the bixverse binary format from disk, but the trait exposes nothing file-specific so that other backends can be added later without touching consumers.

Whether a store is cell-based (CSR, fast per-cell access) or gene-based (CSC, fast per-gene access) is a runtime property of the underlying data, not of the type. Asking a gene-based store for cells returns ScDataErrors::ReaderModeMismatch.

Implementors need only supply read_cells_parallel, read_gene_parallel, get_header and is_cell_based. The rest have default bodies written in terms of those four. Backends that can do better should override: the defaults for read_cell_library_sizes and read_gene_nnz parse whole chunks, whereas a backend able to peek at chunk headers can avoid that.

Send + Sync is required: readers are shared across rayon threads.

Required Methods§

Source

fn read_cells_parallel( &self, indices: &[usize], ) -> Result<Vec<CsrCellChunk>, ScDataErrors>

Read cells by index in a multi-threaded manner

§Params
  • indices - Index positions of the cells to retrieve
§Returns

The CsrCellChunks in the order given by indices.

Source

fn read_gene_parallel( &self, indices: &[usize], ) -> Result<Vec<CscGeneChunk>, ScDataErrors>

Read genes by index in a multi-threaded manner

§Params
  • indices - Index positions of the genes to retrieve
§Returns

The CscGeneChunks in the order given by indices.

Source

fn read_cells_sparse<T>( &self, indices: &[usize], data_layer: &DataLayerReturn, ) -> Result<CompressedSparseData2<T, f32>, ScDataErrors>
where T: BixverseNumeric + FromPrimitive,

Read a batch of cells straight into one CSR matrix.

Same output as Self::read_cells_parallel followed by from_cell_chunks, without materialising a chunk per cell. Prefer it whenever the consumer only needs the counts and indices.

§Params
  • indices - Cell indices, in output row order
  • data_layer - Which layer(s) to materialise
§Returns

CSR of shape (indices.len(), total_genes), raw counts in data (empty when not requested) and normalised counts in data_2, or ScDataErrors::ReaderModeMismatch on a gene-major store and ScDataErrors::RawCountOverflow for a count that does not fit T.

Source

fn read_genes_sparse<T>( &self, indices: &[usize], cells_to_keep: Option<&IndexSet<u32>>, data_layer: &DataLayerReturn, ) -> Result<CompressedSparseData2<T, f32>, ScDataErrors>
where T: BixverseNumeric + FromPrimitive,

Read a batch of genes straight into one CSC matrix, optionally keeping only a cell subset.

Same output as Self::read_gene_parallel_filtered (or Self::read_gene_parallel without a subset) followed by from_gene_chunks, without materialising a chunk per gene. Kept cells are renumbered to their position in cells_to_keep.

§Params
  • indices - Gene indices, in output column order
  • cells_to_keep - Cells to keep, in output row order, or None for all cells
  • data_layer - Which layer(s) to materialise
§Returns

CSC of shape (cells, indices.len()), raw counts in data (empty when not requested) and normalised counts in data_2, or ScDataErrors::ReaderModeMismatch on a cell-major store and ScDataErrors::RawCountOverflow for a count that does not fit T.

Source

fn get_header(&self) -> SparseDataHeader

Return the header of the underlying store

§Returns

The SparseDataHeader.

Source

fn is_cell_based(&self) -> bool

Is the store laid out for fast cell retrieval?

§Returns

true for a cell-based (CSR) store.

Provided Methods§

Source

fn read_gene_parallel_raw( &self, indices: &[usize], ) -> Result<Vec<CscGeneChunk>, ScDataErrors>

Read genes for consumers of the raw counts and indices only.

data_norm may come back empty, so only use it when the consumer never touches that layer. The default reads both layers.

§Params
  • indices - Index positions of the genes to retrieve
§Returns

The CscGeneChunks in the order given by indices.

Source

fn is_gene_based(&self) -> bool

Is the store laid out for fast gene retrieval?

§Returns

true for a gene-based (CSC) store.

Source

fn target_size(&self) -> Option<f32>

Library size the data_norm layer of this store was scaled to.

Needed by anything that has to undo the ln1p(count / lib_size * target_size) normalisation, such as CscGeneChunk::transform_to_clr. Defaults to None for stores that do not record it.

§Returns

Some(target_size), or None when the store cannot report one.

Source

fn read_cell(&self, index: usize) -> Result<CsrCellChunk, ScDataErrors>

Read a single cell by index

§Params
  • index - Cell index
§Returns

The CsrCellChunk of this cell.

Source

fn read_gene(&self, index: usize) -> Result<CscGeneChunk, ScDataErrors>

Read a single gene by index

§Params
  • index - Gene index
§Returns

The CscGeneChunk of this gene.

Source

fn read_cells_range( &self, start: usize, end: usize, ) -> Result<Vec<CsrCellChunk>, ScDataErrors>

Read a contiguous range of cells

Helper for memory-bounded gene generation.

§Params
  • start - First cell index (inclusive)
  • end - Last cell index (exclusive)
§Returns

The CsrCellChunks in that range.

Source

fn get_all_cells(&self) -> Result<Vec<CsrCellChunk>, ScDataErrors>

Return all cells in the store

§Returns

Every CsrCellChunk.

Source

fn get_all_genes(&self) -> Result<Vec<CscGeneChunk>, ScDataErrors>

Return all genes in the store

§Returns

Every CscGeneChunk.

Source

fn read_gene_parallel_filtered( &self, indices: &[usize], cells_to_keep: &IndexSet<u32>, ) -> Result<Vec<CscGeneChunk>, ScDataErrors>

Read genes by index and filter them to a set of cells

§Params
  • indices - Index positions of the genes to retrieve
  • cells_to_keep - Cell index positions to keep, in output order
§Returns

The filtered CscGeneChunks.

Source

fn read_cell_library_sizes( &self, indices: &[usize], ) -> Result<Vec<usize>, ScDataErrors>

Read only the library sizes for the given cells

§Params
  • indices - Cell indices
§Returns

Vector of library sizes in the order given by indices.

Source

fn read_gene_nnz(&self, indices: &[usize]) -> Result<Vec<usize>, ScDataErrors>

Read the NNZ for the given genes

§Params
  • indices - Gene indices
§Returns

Vector of NNZ counts in the order given by indices.

Source

fn get_all_gene_nnz(&self) -> Result<Vec<usize>, ScDataErrors>

Return NNZ for all genes

§Returns

Vector of NNZ values for all genes.

Source

fn get_clr_offsets( &self, indices: &[usize], batch_size: Option<usize>, ) -> Result<Vec<f64>, ScDataErrors>

Compute the shifted CLR per-cell offsets freshly from raw counts.

The offset for cell i is m_i = (1/D) * sum_j log1p(x_ij / s_i), where D is the total gene count and s_i is the cell’s library size. Size factor is fixed at 1, independent of any size factor used during the original normalisation. Cells are read in batches to bound peak memory.

§Params
  • indices - Cell indices to compute offsets for
  • batch_size - Number of cells to load per batch (defaults to CELL_BATCH_SIZE)
§Returns

Vector of CLR offsets in the same order as indices.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§