How vandijklab/cell2sentence works
Project type and purpose
• Cell2Sentence is a Python library and framework (not a web app or microservice) for converting single‑cell gene expression data into “cell sentences” and interfacing with Large Language Models (LLMs) to perform tasks like gene reconstruction, cell type prediction, and conditional cell generation.
• It provides core modules for data ingestion (csdata), model interaction (csmodel), prompt formatting (prompt_formatter), and task orchestration (tasks), packaged along with tutorials, tests, and documentation.
Core components
a. Data Ingestion & Preprocessing (csdata)
• Inputs: raw single‑cell files (.csv, .h5ad)
• Operations: loading, filtering, normalization, rank‑order transformation to produce cell sentences
• Output: structured data objects (e.g., pandas DataFrame, AnnData, or custom CSData objects)
b. Prompt Construction (prompt_formatter)
• Inputs: transformed cell sentences + JSON templates (src/cell2sentence/prompts/*.json)
• Operations: fill template placeholders, assemble natural‑language prompts for specific tasks
• Output: finalized text prompts ready for LLM consumption
c. Model Wrapper & Inference/Finetuning (csmodel)
• Dependencies: Huggingface Transformers (e.g., Pythia), optional Flash‑Attention for speed
• Operations: load pretrained C2S models or fine‑tune on user data (via PyTorch Trainer API), run inference to predict next gene tokens or cell types
• Output: token sequences, embeddings, probabilities, reconstructed expression vectors
d. Task Orchestration (tasks)
• Built‑in pipelines for:
• rank transformation & inverse reconstruction
• embedding extraction
• cell type prediction
• conditional cell generation
• multi‑cell and multi‑task workflows
• Coordinates calls to csdata, prompt_formatter, and csmodel
• Returns final results to the user (arrays, DataFrames, text)
e. Utilities & I/O (utils)
• Logging, caching, evaluation metrics, I/O helpers
f. External Services & Artifacts
• Huggingface Hub for model download/upload
• Optional Flash‑Attention C++ backend
• Tutorials/notebooks (Jupyter) for guided workflows
• Documentation (Sphinx) and CI/CD (GitHub Actions)
Architectural patterns & design principles
• Modular layering: clear separation between data, prompt logic, model interaction, and orchestration
• Adapter pattern: CSModel wraps any Huggingface model to expose consistent C2S‑specific API
• Template method pattern: PromptFormatter processes generic JSON templates for different tasks
• Pipeline orchestration: tasks module as higher‑order functions chaining modules
• Extensibility: JSON‑based prompts, plugin‑style tasks, easy to add new workflows
Technologies, frameworks, and other artifacts
• Python 3.8+
• Dependencies: transformers, torch, scanpy/anndata (for .h5ad), pandas, json, optional flash‑attention
• Packaging: pyproject.toml, setup.cfg, Makefile, Conda environment
• Testing: pytest with sample data under src/cell2sentence/tests
• Documentation: Sphinx config in docs/source, built via ReadTheDocs, CI pipeline in .github/workflows