Struct CellGeneSparseWriter 

pub struct CellGeneSparseWriter { /* private fields */ }

CellGeneSparseWriter

Implementation of a structure for writing in a streamed manner two different types of sparse stored data.

Implementations

impl CellGeneSparseWriter

pub fn new<P: AsRef<Path>>( path_f: P, cell_based: bool, total_cells: usize, total_genes: usize, target_size: f32, ) -> Result<Self, ScDataErrors>

Create a new sparse writer instance

Writes the current file format (v4, lz4 bodies). Use Self::with_codec to pick another body codec, or Self::new_v3 for the legacy format.

This writer assumes that rows represent genes and columns represent cells.

Params

• path_f - Path to the .bin file to which to write to.
• cell_based - Shall the writer be set up for writing cell-based (true) or gene-based chunks.
• total_cells - Total cells in the data.
• total_genes - Total genes in the data.
• target_size - Library size the data_norm layer was normalised against. Pass 0.0 on raw-only paths where no normalisation applies; readers report that as None.

Returns

The CellGeneSparseWriter.

pub fn new_v3<P: AsRef<Path>>( path_f: P, cell_based: bool, total_cells: usize, total_genes: usize, target_size: f32, ) -> Result<Self, ScDataErrors>

Create a writer for the legacy v3 format.

Only needed to produce v3 files on purpose, such as the input of a conversion test. Same parameters as Self::new.

Params

• path_f - Path to the .bin file to which to write to.
• cell_based - Cell-based (true) or gene-based chunks.
• total_cells - Total cells in the data.
• total_genes - Total genes in the data.
• target_size - Library size the normalised layer is scaled to.

Returns

The CellGeneSparseWriter.

pub fn with_codec(self, codec: ChunkCodec) -> Self

Set the body codec of the v4 chunks this writer encodes.

Chunks that do not shrink are stored uncompressed whatever the codec.

Params

• codec - The codec

Returns

The writer, with the codec set.

pub fn format(&self) -> ChunkFormat

How this writer encodes chunks.

Parallel payload builders copy this out and encode with it, so what they hand to the write_compressed_* methods matches the file.

Returns

The format: file version, body codec and the header target size.

pub fn set_cell_library_table( &mut self, table: Vec<u64>, ) -> Result<(), ScDataErrors>

Set the per-cell library-size table of a v4 gene-based file.

Gene chunks that drop their norm layer recompute it from the library size of each cell, so the table has to be set before Self::finalise. The chunks must have been encoded against the same table, see ChunkFormat::encode_gene.

Params

• table - Library size per original cell index

Returns

Ok(()), or an error unless this is a v4 gene-based writer.

pub fn write_cell_chunk( &mut self, cell_chunk: CsrCellChunk, ) -> Result<(), ScDataErrors>

Write a Cell (Chunk) to the file

The data is represented in a CSR-type format.

Params

• cell_chunk - The data representing that specific cell.

Returns

Ok(()), or ScDataErrors::ReaderModeMismatch if the writer was opened for gene-based chunks.

pub fn write_gene_chunk( &mut self, gene_chunk: CscGeneChunk, ) -> Result<(), ScDataErrors>

Write a Gene to the file

A v4 gene chunk written this way keeps its normalised layer verbatim, since there is no per-cell library table to recompute it from. The bulk path, write_gene_file, drops it.

Params

• gene_chunk - The data representing that specific gene.

Returns

Ok(()), or ScDataErrors::ReaderModeMismatch if the writer was opened for cell-based chunks.

pub fn write_compressed_gene_chunks( &mut self, chunks: &[(usize, Vec<u8>)], ) -> Result<(), ScDataErrors>

Write genes whose payloads were already built via ChunkFormat::encode_gene of this writer’s Self::format.

Params

• chunks - (original_index, payload) pairs, appended in the given order.

Returns

Ok(()), or ScDataErrors::ReaderModeMismatch if the writer was opened for cell-based chunks.

pub fn write_compressed_cell_chunks( &mut self, chunks: &[CellPayload], ) -> Result<(), ScDataErrors>

Write cells whose payloads were already built via ChunkFormat::encode_cell of this writer’s Self::format.

Params

• chunks - Cell payloads, appended in the given order.

Returns

Ok(()), or ScDataErrors::ReaderModeMismatch if the writer was opened for gene-based chunks.

pub fn finalise(self) -> Result<(), ScDataErrors>

Finalise the file

Writes the SparseDataHeader tail and, for cell-based files, the library-size index (Self::write_library_index), then rewrites the fixed 64-byte file header at offset zero with both offsets.

Returns

Ok(()) on success, ScDataErrors::HeaderEncodeFailed if either header could not be encoded.

pub fn update_header_no_cells(&mut self, no_cells: usize)

Update the number of cells in the header

Helper function to update the number of cells to the number that was finally written on disk.

Params

• no_cells - New number of cells

pub fn update_header_no_genes(&mut self, no_genes: usize)

Update the number of cells in the header

Helper function to update the number of genes to the number that was finally written on disk.

Params

• no_genes - New number of genes