Getting Started

Installation

npm

npm install deg.js

pnpm

pnpm add deg.js

yarn

yarn add deg.js

Basic Usage

import { rankGenesGroups } from 'deg.js';

// 1. Prepare expression data (cells × genes, row-major)
const expression = {
  data: new Float32Array(nCells * nGenes),  // row-major layout
  nCells: 1000,
  nGenes: 5000,
};

// 2. Prepare group information
const groups = {
  groupLabels: new Uint32Array(nCells),     // 0, 1, 2, ... for each cell
  groupNames: ['ClusterA', 'ClusterB', 'ClusterC'],
  nGroups: 3,
};

// 3. Run analysis
const result = await rankGenesGroups(expression, groups, {
  geneNames: ['Gene1', 'Gene2', ...],       // optional
  nGenes: 100,                               // top 100 genes per group
  corrMethod: 'benjamini-hochberg',          // p-value correction
});

// 4. Access results
for (const [groupName, groupResult] of result.groups) {
  console.log(`\n=== ${groupName} ===`);
  console.log('Top 10 genes:', groupResult.names.slice(0, 10));
  console.log('Z-scores:', groupResult.scores.slice(0, 10));
  console.log('P-values:', groupResult.pvals.slice(0, 10));
  console.log('Log2 FC:', groupResult.logFoldChanges.slice(0, 10));
}

Data Layout

deg.js expects expression data in row-major format by default:

cell0_gene0, cell0_gene1, cell0_gene2, ...,
cell1_gene0, cell1_gene1, cell1_gene2, ...,
...

You can also use column-major format by specifying the layout:

const expression = {
  data: new Float32Array(nCells * nGenes),
  nCells: 1000,
  nGenes: 5000,
  layout: 'column-major',  // gene0_cell0, gene0_cell1, ...
};

Understanding the Results

The rankGenesGroups function returns a RankGenesResult object:

interface RankGenesResult {
  groups: Map<string, GroupResult>;  // Results per group
  params: RankGenesParams;           // Analysis parameters
}

interface GroupResult {
  names: string[];           // Gene names (sorted by score)
  scores: Float32Array;      // Z-scores from Wilcoxon test
  pvals: Float64Array;       // Two-sided p-values
  pvalsAdj: Float64Array;    // Adjusted p-values (FDR or Bonferroni)
  logFoldChanges: Float32Array;  // Log2 fold changes
}

Interpreting Z-scores

• Positive Z-score: Gene is upregulated in this group compared to others
• Negative Z-score: Gene is downregulated in this group
• Higher absolute value: Stronger differential expression

P-value Correction

Two methods are available:

• Benjamini-Hochberg (default): Controls False Discovery Rate (FDR). Less conservative, higher power.
• Bonferroni: Controls Family-Wise Error Rate (FWER). Very conservative.

// Benjamini-Hochberg (recommended)
const result = await rankGenesGroups(expression, groups, {
  corrMethod: 'benjamini-hochberg',
});

// Bonferroni (more conservative)
const result = await rankGenesGroups(expression, groups, {
  corrMethod: 'bonferroni',
});

Checking GPU Support

import { isWebGPUAvailable } from 'deg.js';

if (isWebGPUAvailable()) {
  console.log('WebGPU available - using fastest backend');
} else {
  console.log('Falling back to WebGL2');
}

Next Steps

• API Reference - Detailed function documentation
• Advanced Usage - Streaming, chunked loading, custom sources
• Architecture - Technical deep dive