API Reference

Core Functions

rankGenesGroups

The main entry point for differential expression analysis.

async function rankGenesGroups(
  expression: ExpressionInput,
  groups: GroupInfo,
  options?: RankGenesGroupsOptions
): Promise<RankGenesResult>

Parameters

Parameter	Type	Description
expression	ExpressionInput	Expression matrix or chunked matrix
groups	GroupInfo	Group assignment for each cell
options	RankGenesGroupsOptions	Analysis options (optional)

Options

Option	Type	Default	Description
backend	'auto' | 'webgpu' | 'webgl2'	'auto'	GPU backend selection
reference	null | string	undefined	Reference group for comparison (default: all other cells)
nGenes	number	all	Number of top genes to return
corrMethod	'benjamini-hochberg' | 'bonferroni'	'benjamini-hochberg'	P-value correction method
tieCorrect	boolean	false	Apply tie correction to Z-scores
rankbyAbs	boolean	false	Rank by absolute Z-score
logBase	number	Math.E	Log base for fold change calculation
geneNames	string[]	['gene_0', ...]	Names for each gene
groups	'all' | string[]	'all'	Groups to analyze
streaming	'auto' | boolean	'auto'	Enable streaming mode
maxMemoryMB	number	2048	Maximum GPU memory usage (MB)
sortAlgorithm	'auto' | 'bitonic' | 'radix'	'auto'	Sorting algorithm (WebGPU only)
onProgress	(progress: StreamingProgress) => void	-	Progress callback

Returns

interface RankGenesResult {
  groups: Map<string, GroupResult>;
  params: RankGenesParams;
}

Example

import { rankGenesGroups } from 'deg.js';

const result = await rankGenesGroups(expression, groups, {
  nGenes: 100,
  corrMethod: 'benjamini-hochberg',
  onProgress: (p) => console.log(`${p.genesProcessed}/${p.totalGenes}`),
});

---

Types

ExpressionMatrix

Standard expression matrix with all data in memory.

interface ExpressionMatrix {
  data: Float32Array;         // Expression values
  nCells: number;             // Number of cells
  nGenes: number;             // Number of genes
  layout?: 'row-major' | 'column-major';  // Default: 'row-major'
}

ChunkedExpressionMatrix

Lazy-loading expression matrix for large datasets.

interface ChunkedExpressionMatrix {
  nCells: number;
  nGenes: number;
  layout?: 'row-major' | 'column-major';
  getGeneChunk: (startGene: number, nGenes: number) => GeneChunkData | Promise<GeneChunkData>;
}

interface GeneChunkData {
  data: Float32Array;
  nGenes: number;
  layout?: 'row-major' | 'column-major';
}

GroupInfo

Group assignment information.

interface GroupInfo {
  groupLabels: Uint32Array;   // Group index (0-indexed) for each cell
  groupNames: string[];       // Human-readable group names
  nGroups: number;            // Total number of groups
}

GroupResult

Results for a single group.

interface GroupResult {
  names: string[];              // Gene names (sorted by score)
  scores: Float32Array;         // Z-scores
  pvals: Float64Array;          // P-values
  pvalsAdj: Float64Array;       // Adjusted p-values
  logFoldChanges: Float32Array; // Log2 fold changes
}

StreamingProgress

Progress information during streaming mode.

interface StreamingProgress {
  chunksProcessed: number;
  totalChunks: number;
  genesProcessed: number;
  totalGenes: number;
  elapsedMs: number;
  estimatedRemainingMs: number;
}

---

Utility Functions

isWebGPUAvailable

Check if WebGPU is available in the current environment.

function isWebGPUAvailable(): boolean

Type Guards

// Check if expression is chunked (lazy loading)
function isChunkedExpression(expr: ExpressionInput): expr is ChunkedExpressionMatrix

// Check if expression is full matrix (all data in memory)
function isFullExpression(expr: ExpressionInput): expr is ExpressionMatrix

---

See Also

• Getting Started - Basic usage tutorial
• Advanced Usage - Streaming and chunked loading
• Architecture - Technical deep dive