---
title: Scanpy inputs and parameters
description: Input format and every QC, feature-selection, clustering, and DE parameter for Scanpy.
---

You provide one AnnData `.h5ad` file plus the parameters for your chosen workflow. The values that most affect the result are the QC cutoffs — minimum genes per cell, maximum mitochondrial percent, and the number of highly variable genes — because they decide which cells and genes survive into clustering. Everything else has a sensible default keyed to the GPU pipeline.

## Input format

The platform's Scanpy job reads a single **AnnData `.h5ad`** file from storage. The URL must be an S3 URI (`s3://…`) or an HTTPS URL (`https://…`) and must end in `.h5ad` — the pipeline validates both.

| Requirement | Detail |
|-------------|--------|
| Format | AnnData (`.h5ad`) only |
| Location | S3 URI or HTTPS URL |
| Contents | Cells × genes count matrix in `X`, gene symbols in `var` |

If you have 10X Cell Ranger output, a CSV count matrix, or another format, convert it to `.h5ad` before submitting.

## Workflow selection

| Value | What runs |
|-------|-----------|
| `full` (default) | QC → normalize → HVG → PCA → UMAP → Leiden → differential expression |
| `qc` | Quality control and filtering only |
| `clustering` | QC through Leiden clustering + UMAP (no markers) |
| `de` | Differential expression / marker genes |

The tool also exposes CPU-based extension workflows — `harmony_integrate`, `scanorama_integrate`, `combat_correct` (batch correction), `celltypist_annotate` (annotation), `aucell_score`, `cosg_markers`, `hotspot_modules`, `cytotrace2_potency`, `scvelo_velocity`. Batch-correction workflows require a `batch_key` naming the `obs` column with sample labels.

## Quality-control parameters

| Parameter | Range | Default | What it does |
|-----------|-------|---------|--------------|
| `min_genes` | 1–5000 | 200 | Drop cells with fewer detected genes (empty droplets) |
| `min_cells` | 1–100 | 3 | Drop genes seen in fewer cells |
| `max_genes` | integer | none | Optional upper bound (possible doublets) |
| `max_mito_percent` | 0–50 | 5 | Drop cells above this mitochondrial fraction (dying cells) |

> The platform defaults to a **5%** mitochondrial cutoff — stricter than the 20% often seen in tutorials. Relax `max_mito_percent` if QC filters out too many cells (a common cause of an "empty after filtering" error).

## Feature selection and dimensionality reduction

| Parameter | Range | Default | What it does |
|-----------|-------|---------|--------------|
| `n_top_genes` | 100–10000 | 2000 | Number of highly variable genes to keep |
| `hvg_flavor` | `cell_ranger` · `seurat` · `seurat_v3` | `seurat` | HVG selection method |
| `n_pcs` | 2–100 | 50 | Principal components for the neighbor graph |
| `n_neighbors` | 2–100 | 15 | Neighbors in the kNN graph |

## Clustering and differential expression

| Parameter | Range | Default | What it does |
|-----------|-------|---------|--------------|
| `resolution` | 0.1–2.0 | 1.0 | Cluster granularity — higher gives more, smaller clusters |
| `clustering_method` | `leiden` · `louvain` | `leiden` | Community-detection algorithm |
| `method` | `wilcoxon` · `t-test` · `logreg` | `wilcoxon` | Marker-gene ranking test |
| `de_groups` | list | none | Restrict DE to specific clusters |

## Output options

| Parameter | Default | What it does |
|-----------|---------|--------------|
| `generate_figures` | `true` | Produce UMAP and violin plots |
| `figure_format` | `png` | `png`, `pdf`, or `svg` |

## Read next