Skip to main content

Shared Module

The shared module provides common functionality, types, and traits used throughout the SingleRust library. This module serves as the foundation for consistent data handling and operations across different components.

Overview​

pub mod shared;

The shared module contains:

  • Common enums and types
  • Core traits for statistical operations
  • Utility functions for data conversion
  • Plot settings and visualization components

Core Types​

Direction​

Specifies the dimension along which operations should be performed.

pub enum Direction {
    Row = 0,     // Operate on rows (typically cells)
    Column = 1,  // Operate on columns (typically genes)
}

Methods​

  • is_row(&self) -> bool: Returns true if direction is Row
  • is_column(&self) -> bool: Returns true if direction is Column

Example​

use single_rust::Direction;

// Specify direction for normalization
normalize_expression(&matrix, 10000, &Direction::Row, None)?;

Precision​

Specifies the floating-point precision for numerical operations.

pub enum Precision {
    Single,  // 32-bit float (f32)
    Double,  // 64-bit float (f64)
}

Example​

use single_rust::Precision;

// Specify precision for type conversion
convert_to_float_if_non_float_type(&matrix, Some(Precision::Double))?;

FlexValue​

Represents a flexible value specification that can be absolute, relative, or none.

pub enum FlexValue {
    Absolute(f32),  // Absolute value
    Relative(f32),  // Relative value (percentage)
    None,           // No value specified
}

Methods​

  • is_absolute(&self) -> bool: Returns true if value is absolute
  • is_relative(&self) -> bool: Returns true if value is relative
  • is_none(&self) -> bool: Returns true if no value is specified
  • is_some(&self) -> bool: Returns true if a value is specified

FeatureSelection​

Specifies methods for selecting features/genes.

pub enum FeatureSelection {
    HighlyVariableCol(String),  // Select based on column in var
    HighlyVariable(usize),      // Select top N highly variable genes
    Randomized(usize),          // Select N random genes
    VarianceThreshold(f64),     // Select genes above variance threshold
    None,                       // No selection
}

ComputationMode​

Specifies how computation should be performed (in chunks or as a whole).

pub enum ComputationMode {
    Chunked(usize),  // Process in chunks of specified size
    Whole,           // Process all data at once
}

Core Traits​

The shared module defines several traits that provide statistical operations:

ComputeNonZero​

pub trait ComputeNonZero {
    fn nonzero_whole<T>(&self, direction: &Direction) -> anyhow::Result<Vec<T>>
    where
        T: PrimInt + Unsigned + Zero + AddAssign;

    fn nonzero_chunk<T>(&self, direction: &Direction, reference: &mut [T]) -> anyhow::Result<()>
    where
        T: PrimInt + Unsigned + Zero + AddAssign;
}

ComputeSum​

pub trait ComputeSum {
    fn sum_whole<T>(&self, direction: &Direction) -> anyhow::Result<Vec<T>>
    where
        T: Float + NumCast + AddAssign + Sum;

    fn sum_chunk<T>(&self, direction: &Direction, reference: &mut [T]) -> anyhow::Result<()>
    where
        T: Float + NumCast + AddAssign + Sum;
}

ComputeVariance​

pub trait ComputeVariance {
    fn variance_whole<I, T>(&self, direction: &Direction) -> anyhow::Result<Vec<T>>
    where
        I: PrimInt + Unsigned + Zero + AddAssign + Into<T>,
        T: Float + NumCast + AddAssign + Sum;

    fn variance_chunk<I, T>(&self, direction: &Direction, reference: &mut [T]) -> anyhow::Result<()>
    where
        I: PrimInt + Unsigned + Zero + AddAssign + Into<T>,
        T: Float + NumCast + AddAssign + Sum;
}

ComputeMinMax​

pub trait ComputeMinMax {
    fn min_max_whole<T>(&self, direction: &Direction) -> anyhow::Result<(Vec<T>, Vec<T>)>
    where
        T: NumCast + Copy + PartialOrd + NumericOps;

    fn min_max_chunk<T>(&self, direction: &Direction, reference: (&mut Vec<T>, &mut Vec<T>)) -> anyhow::Result<()>
    where
        T: NumCast + Copy + PartialOrd + NumericOps;
}

Utility Functions​

convert_to_array_f64​

Converts different array types to Array2<f64>.

pub fn convert_to_array_f64(arr_data: &ArrayData) -> anyhow::Result<Array2<f64>>

Parameters​

  • arr_data: The array data to convert

Returns​

  • anyhow::Result<Array2<f64>>: Converted array or error

Example​

let dense_array = convert_to_array_f64(&sparse_matrix)?;

convert_to_array_f64_selected​

Converts a subset of array data to Array2<f64> based on row and column selections.

pub fn convert_to_array_f64_selected(
    data: &ArrayData,
    shape: Shape,
    row_selection: &SelectInfoElem,
    col_selection: &SelectInfoElem
) -> anyhow::Result<Array2<f64>>

Parameters​

  • data: The array data to convert
  • shape: Shape of the array
  • row_selection: Row selection criteria
  • col_selection: Column selection criteria

Returns​

  • anyhow::Result<Array2<f64>>: Converted array subset or error

Processing Utilities​

The shared module also includes utility functions for processing data:

get_select_info_obs​

Creates selection information for observations based on a boolean mask.

pub fn get_select_info_obs(
    obs_mask: Option<ArrayView<'_, bool, Ix1>>
) -> anyhow::Result<Vec<SelectInfoElem>>

get_select_info_vars​

Creates selection information for variables based on a boolean mask.

pub fn get_select_info_vars(
    vars_mask: Option<ArrayView<'_, bool, Ix1>>
) -> anyhow::Result<Vec<SelectInfoElem>>

HVG Parameters​

HVGParams​

Parameters for highly variable gene selection.

pub struct HVGParams {
    pub min_mean: f64,
    pub max_mean: f64,
    pub min_dispersion: f64,
    pub max_dispersion: f64,
    pub n_bins: usize,
    pub n_top_genes: Option<usize>,
    pub flavor: FlavorType,
    pub span: f64,
    pub batch_key: Option<String>,
}

FlavorType​

Statistical method for identifying highly variable genes.

pub enum FlavorType {
    Seurat,
    CellRanger,
    SVR,
}