User Guide

Welcome to the scXpand User Guide! This comprehensive guide follows the typical user workflow for T-cell expansion prediction using single-cell RNA sequencing data.

Quick Start

Get up and running with scXpand in minutes:

import scxpand

# List available pre-trained models
scxpand.list_pretrained_models()

# Run inference with automatic model download
results = scxpand.run_inference(
    model_name="pan_cancer_autoencoder",  # default model
    data_path="your_data.h5ad"
)

# Access predictions
predictions = results.predictions
if results.has_metrics:
    print(f"AUROC: {results.get_auroc():.3f}")

For more detailed workflows, see the sections below.

Documentation Structure

Setup & Installation

• Installation Guide
  • Installing the Published Package
  • Development Setup (from Source)

Data Preparation

• Input Data Format Specification
  • Gene Expression Matrix (X)
  • Gene Annotations (var)
  • Cell Annotations (obs)
• Data Pipeline & Normalization
  • Overview
• Pipeline Architecture
  • Core Components
  • Data Input Modes
  • Normalization Details
  • Gene Format Handling
  • Data Augmentation
• Inference Data Format Handling

Using Pre-trained Models

• Model Inference
  • Programmatic API
  • Handling Data Format Mismatches
  • Inference API Reference
  • Pre-trained Models

CLI Reference

• Command-Line Interface (CLI) Reference
  • Main Commands

Training Your Own Models

• Model Training
  • Overview
  • Training with the Command-Line
  • Using a Configuration File
  • Training API Reference
  • Training Monitoring
• Data Splitting Strategy
  • Overview
• Multi-Level Data Splitting Strategy
  • Key Principles
  • Implementation Details
  • Reproducibility
  • Integration with Training Pipeline
• Hyperparameter Optimization Guide
  • Overview
  • Reproducibility and Data Splitting
  • Quick Start
  • Results Analysis
  • Custom Configuration
  • Optimization System Architecture
• API Reference
  • Hyperparameter Optimization Functions
  • Hyperparameter Search Ranges

Understanding Models & Results

• Model Architectures Guide
  • Overview
• Available Model Architectures
  • Autoencoder-Based Models
  • Multi-Layer Perceptron (MLP)
  • LightGBM Models
  • Linear Models
• Evaluation & Metrics Guide
  • Overview
• Multi-Level Performance Evaluation
  • Core Metrics
  • Stratified Evaluation
  • Aggregation Methods
  • Evaluation Workflow
• Output Format Specification
  • Overview
  • Common Files (All Models)
  • Model Files (Model-Specific)
  • Visualization Files
  • PyTorch Model Files (autoencoder, mlp)
  • Autoencoder and MLP-Specific Files
  • Linear Model Files (logistic, svm)
  • Hyperparameter Optimization Files
  • Model Type File
  • Directory Structure Example