Get data into an AnnData object and results back out. The scRNA-seq loaders cover H5AD, 10x H5 and MTX, CSV/TSV, Loom, plain text, and the two RNA-velocity formats (velocyto .loom and STARsolo Velocyto output). The utilities attach a sample sheet, merge datasets with a live preview, subset with an AND/OR builder, define custom groups, split composite cell IDs, browse and tidy obs columns, and export tables. Spatial, bulk, methylation and ATAC loaders live in their own categories.
Good to know
Merge Cell Meta is the standard way to attach phenotype or a sample sheet — in scRNA-seq, bulk and methylation alike. Its auto match mode picks the key column the same way in the preview and in the run, so a preview that shows 100% no longer ends in a rejected run (fixed in v0.25.0).
Export CSV writes 15 tabular result types. The numbers behind a specific figure are exported from that figure’s Visualization Workspace instead (Export raw data).
Loaders convert a matrix that was stored dense on disk to sparse on load (v0.25.0). If a memory refusal mentions a dense matrix on an older project, re-running the loader is usually the whole fix — see Memory & large data.
Common pitfalls
Load CSV / TSV is for expression matrices, not metadata. Cell-level metadata goes through Merge Cell Meta; spatial coordinates go through Add Coordinates.
Genes-as-rows files need transpose. A cells × genes matrix loads as-is; a genes × cells export must be transposed or every gene becomes a cell.
Load Loom is not Load Velocyto Loom. Only the velocyto loader keeps the spliced / unspliced / ambiguous layers that RNA Velocity needs.
Load an .h5ad file into AnnData. Native scanpy/AnnData format — preserves all metadata, layers, and embeddings. Duplicate gene names are made unique automatically.
| Name | Type | Default | Description |
|---|---|---|---|
file_path | file (.h5ad) | — | Path to the .h5ad file. |
Load 10X Genomics HDF5 (.h5) from Cell Ranger output. Use filtered_feature_bc_matrix.h5 unless empty droplets are needed. Specify genome for multi-genome files.
| Name | Type | Default | Description |
|---|---|---|---|
file_path | file (.h5) | — | Path to the 10X .h5 file. |
genome | text | — | Genome identifier (leave empty to auto-detect). |
Load 10X Genomics MTX directory (matrix.mtx + features + barcodes). Validates Matrix Market header before loading. var_names="gene_symbols" for human-readable names; "gene_ids" for Ensembl IDs.
| Name | Type | Default | Description |
|---|---|---|---|
directory_path | directory | — | Path to Cell Ranger output directory. |
var_names | select | gene_symbols | "gene_symbols" or "gene_ids". |
make_unique | checkbox | true | Make variable names unique. |
Load a CSV/TSV expression matrix (cells × genes). NOT for cell metadata — use Merge Cell Meta for that. Delimiter auto-detected from .tsv/.txt extension.
| Name | Type | Default | Description |
|---|---|---|---|
file_path | file (.csv, .tsv, .txt) | — | Path to the expression matrix file. |
delimiter | select | , | "," for CSV, "\t" for TSV. |
first_column_names | checkbox | true | First column as cell names. |
transpose | checkbox | false | Transpose if genes are rows. |
Load a Loom file. Use Load Velocyto Loom for RNA velocity layers.
| Name | Type | Default | Description |
|---|---|---|---|
file_path | file (.loom) | — | Path to the .loom file. |
sparse | checkbox | true | Load as sparse matrix. |
| Name | Type | Default | Description |
|---|---|---|---|
file_path | file (.txt, .tsv) | — | Path to the text file. |
delimiter | select | \t | Field separator. |
first_column_names | checkbox | true | First column as cell names. |
transpose | checkbox | false | Transpose the matrix. |
Load a velocyto .loom for RNA velocity (spliced/unspliced/ambiguous layers). Cell barcodes with sample prefixes (e.g. "sample:AAAC...") are stripped automatically. Connect directly to RNA Velocity.
| Name | Type | Default | Description |
|---|---|---|---|
file_path | file (.loom) | — | Path to the velocyto .loom file. |
Load STARsolo Velocyto MTX directory (spliced/unspliced/ambiguous). Run STARsolo with --soloFeatures Velocyto. STARsolo MTX files are genes × cells — auto-transposed.
| Name | Type | Default | Description |
|---|---|---|---|
directory_path | directory | — | Path to STARsolo filtered/ directory. |
Concatenate multiple AnnData objects with per-input labels and live pre-merge preview. v0.9.0-beta.41+ — labels are entered per-input as cards (NOT comma-separated). Outer = keep all genes, Inner = shared genes only. Layer selection is explicit checkboxes.
| Name | Type | Default | Description |
|---|---|---|---|
batch_key | text | batch | Column added to obs identifying source dataset. |
batch_labels_list | array | [] | Per-input labels prefilled from source node names. |
batch_labels | text | — | LEGACY — comma-separated labels. Auto-converted to batch_labels_list for backward-compat. |
join | text | outer | "outer" keeps all genes (0-fill), "inner" shared only. |
keep_layers | array | [] | Explicit list of layers to keep. Overrides layer_strategy. |
layer_strategy | text | common_only | "common_only" or "keep_all" fallback. |
Attach external metadata CSV/TSV/Excel to adata.obs with auto-match suggestions and live match-rate preview. v0.9.0-beta.41+. The canonical way to attach phenotype info (group, batch, age, etc.). Two modes: cell_id (1 row per cell) or obs_column (broadcast group-level metadata).
| Name | Type | Default | Description |
|---|---|---|---|
meta_file | text | — | Path to metadata file. |
match_by | text | auto | "auto", "cell_id", or "obs_column". |
id_col | text | — | CSV column of cell IDs (cell_id mode). |
obs_match_col | text | — | obs column used as matching key (obs_column mode). |
meta_key_col | text | — | CSV column of broadcast values (obs_column mode). |
selected_columns | array | [] | Columns to add. Empty = all except key. |
unmatched_strategy | text | fill_nan | "fill_nan", "drop_cells", or "error". |
allow_positional_fallback | checkbox | false | Off by default; explicit opt-in. |
Filter cells or genes using multi-condition AND/OR builder with live preview. v0.9.0-beta.41+ — replaces the single-condition form. Categorical → multi-select; numeric → range slider + histogram; gene name → async autocomplete + regex.
| Name | Type | Default | Description |
|---|---|---|---|
filter_type | text | cells | "cells" or "genes". |
operation | text | keep | "keep" or "exclude". |
combine_mode | text | AND | How conditions combine. |
conditions | array | [] | List of {column, operator, values?, range?, pattern?}. |
Assign cells to custom categorical groups via multi-condition rules; same label across groups acts as OR. Each group is an AND of conditions → one label. Overlap between different-labeled groups is a hard error. Pairs naturally with Subset Data, DEG Analysis, CellPhoneDB.
| Name | Type | Default | Description |
|---|---|---|---|
result_column | text | custom_group | New obs column name. |
unmatched_label | text | — | Empty → NaN; non-empty fills unmatched cells with that label. |
ordered | checkbox | true | Write pd.Categorical with ordered=True. |
groups | array | [] | List of {id, label, conditions: [...]}. Conditions within a group combine with AND. |
Split cell IDs by delimiter into new obs columns (e.g. B_cac10_AAACCTGAG → type/patient/barcode). Place after Load and before QC. Use the new obs columns with Subset Data for group-specific QC. Original cell IDs are preserved as obs_names.
| Name | Type | Default | Description |
|---|---|---|---|
delimiter | select | _ | Character to split on. "_", "-", ".", or custom. |
custom_delimiter | text | — | Free-form delimiter used when delimiter='custom'. Ignored otherwise. |
column_names | text | — | Names for new obs columns (e.g. type,patient,barcode). |
Browse adata.obs and apply small obs edits (drop / rename / dtype convert) in one node. Dedicated UI: multi-select autocompletes, rename pair editor, inline obs preview table, per-column summary accordion (dtype, n_unique, n_missing, value_counts top N bar chart, sample uniques). Read-only outputs are always computed against the post-edit obs. Operation order within a run: drop → rename → to_category → to_string. Missing targets are silently skipped and reported back. All edits are recorded as params so workflows stay reproducible.
| Name | Type | Default | Description |
|---|---|---|---|
preview_limit | number | 50 | Top-N rows of obs to send to the frontend table (1–500). |
value_counts_top_n | number | 10 | How many most-frequent values per column to include in the summary. |
drop_columns | array | [] | Obs column names to delete. Frontend writes array; legacy comma-string also accepted. |
rename_pairs | array | [] | List of {old, new} dicts. Preferred over rename_map. |
rename_map | text | — | LEGACY — comma-separated 'old:new' pairs ('leiden:cluster, sample:patient'). Used only when rename_pairs is empty/missing. Hand-edited workflow JSONs only — DO NOT emit from AI Chat (use rename_pairs instead). |
to_category | array | [] | Obs columns to convert to Categorical. |
to_string | array | [] | Obs columns to convert to plain string. |
| Name | Type | Default | Description |
|---|---|---|---|
output_path | file path | — | Output .h5ad path. |
compression | select | gzip | "gzip", "lzf", or "none". |
Export analysis results to CSV — 15 export types (markers, pathway, obs, var, lineage_drivers, fate_probabilities, cpdb, bulk_de, gsea, atac_*, dmp, dmr, transcripts, xenium). markers exports a wide-format DEG table with all genes. Each export type has its own column schema.
| Name | Type | Default | Description |
|---|---|---|---|
export_type | select | markers | One of 15 supported export types. |
output_path | file path | — | Output CSV path. |
marker_key | text | rank_genes_groups | adata.uns key for DEG results. |
marker_groups | select | — | Which DEG groups to export (subset of clusters/conditions), as a list or comma-separated names. Empty = export all groups. Only used when export_type='markers'. Requesting a group that does not exist errors with the available group list. |
uns_key | text | pathway_enrichment | adata.uns key for pathway data. |
gene_set_filter | text | — | Pathway gene-set substring filter. |
run_id | text | — | Which functional-activity run to export, as reported in the activity node's result. Empty = the most recent run stored in adata.uns['bf_activity_v1']. Only used when export_type='activity'; matters when a workflow chains PROGENy, Hallmark and CollecTRI in sequence, because all three runs live in the same AnnData and the newest one wins by default. |
obs_column | obs column | — | Specific obs column (xenium type only). |
