Extract metadata using several conditions (conditions are combined with AND)

August 13, 2026 · View on GitHub

adview

Adview: Anndata Viewer: inspect and validate AnnData (.h5ad) files directly in your terminal—without starting Python or loading the full expression matrix.

Why adview

Are you still doing this?:

❯ python3
Python 3.13.2 (main, Feb  4 2025, 14:51:09) [Clang 16.0.0 (clang-1600.0.26.6)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import scanpy as sc   ## hold on, be patient with your HPC🚬
>>> adata = sc.read_h5ad('path/to/adata.h5ad')
>>> adata.var
>>> adata.obs
>>> adata.shape

I just want to glance！👀

Now, let adview comfort you!

Installation

HPC / cluster (recommended)

Use the HDF5 module already installed by the cluster. HDF5 1.8, 1.10, 1.12, and 1.14 are supported.

module avail hdf5
module load hdf5

# If the module is not discovered automatically:
export HDF5_DIR="$(dirname "$(dirname "$(command -v h5cc)")")"

cargo build --release

Keeping HDF5 external makes compilation faster and uses much less memory. If the cluster exposes several compiler toolchains, load HDF5 and the GCC version used to build it from the same module stack.

Bundled HDF5 fallback

If no compatible HDF5 module exists, adview can build HDF5 itself:

# -j 1 limits peak memory on login/build nodes
cargo build --release --features bundled-hdf5 -j 1

The bundled build includes standard gzip/deflate and Blosc with its Zstd codec, so these common H5AD compression modes do not require a plugin directory. This fallback takes longer and requires CMake plus a C compiler. A SIGKILL during hdf5-metno-src normally means the node killed the C build for exceeding its memory or job limits; compile it in an allocated build job rather than on a restricted login node.

Source installation

git clone https://github.com/JianYang-Lab/adview.git
cd adview
cargo build --release
./target/release/adview -h

To include lightweight SVG plotting:

cargo build --release --features plot

or just

cargo install --git https://github.com/JianYang-Lab/adview.git
adview -h

Install with plotting enabled:

cargo install --git https://github.com/JianYang-Lab/adview.git --features plot

Quick start

❯ adview -h
adview -- Fast, Python-free AnnData inspection in your terminal

Version: 0.2.0

Authors: wenjiewei<weiwenjie@westlake.edu.cn>

Usage: adview <COMMAND>

Commands:
  head      Show the first n rows of a group [aliases: h]
  all       Stream every row of a group [aliases: a]
  sample    Show rows spread across an entire group
  shape     Show group lengths [aliases: s]
  field     Show fields in groups [aliases: f]
  info      Show an AnnData-aware file summary [aliases: i]
  tree      Show the HDF5 hierarchy, shapes, and data types [aliases: t]
  validate  Check AnnData structural consistency [aliases: v]
  matrix    Preview a block of X or a layer without loading the full matrix [aliases: x]
  storage   Describe compression, chunking, size, and sparse access orientation
  summarize Summarize obs/var field distributions and missingness
  query     Extract table records or a backed matrix window
  stats     Stream numerical statistics from X or a layer
  edit      Safely modify an AnnData file
  plot      Create lightweight AnnData-aware SVG previews (with feature `plot`)
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Example

Start with a compact summary:

adview info data.h5ad

File: data.h5ad
Size: 2.4 GiB
Shape: 15235 cells × 36601 variables
X: csr_matrix 15235 × 36601
Slots: obs, var, obsm, layers, uns
obs: 4 columns
var: 3 columns

Preview metadata. Select columns with -c and filter literal text with --where COLUMN=TEXT:

❯ adview head -n 5 -c _index,batch --where batch=12 path/to/adata.h5ad

_index                  batch
AAACCCAAGACTTCGT        126
AAACCCAAGCCTTTGA        126
AAACCCAAGTATGAAC        128
AAACCCAAGTCCGTCG        128
AAACCCAAGTGCAACG        128

❯ adview head -g var -n 5 path/to/adata.h5ad

_index  feature_types   gene_symbols
ENSG00000243485 Gene Expression MIR1302-2HG
ENSG00000237613 Gene Expression FAM138A
ENSG00000186092 Gene Expression OR4F5
ENSG00000238009 Gene Expression AL627309.1
ENSG00000239945 Gene Expression AL627309.3

❯ adview s path/to/adata.h5ad

obs shape: 15235
var shape: 36601

❯ adview f path/to/adata.h5ad

obs fields:
        batch (categorical)
        _index (string-array)
        gene_count (array)
        umi_count (array)

var fields:
        _index (string-array)
        feature_types (categorical)
        gene_symbols (categorical)

Sample rows from the beginning, middle, and end of a large table:

adview sample -g obs -n 10 -c _index,batch,cell_type data.h5ad

Inspect structure or run consistency checks:

adview tree --depth 3 data.h5ad
adview validate data.h5ad

validate checks dataframe column lengths, unique indices, categorical codes, X/layer/embedding shapes, and CSR/CSC sparse matrix structure. It returns exit code 2 when errors are found, which makes it suitable for data-delivery and pipeline checks.

Read a small expression block without loading the full matrix:

# Rows 100–104 and columns 20–24 from X
adview matrix --row 100 --rows 5 --column 20 --columns 5 data.h5ad

# The same region from a layer
adview matrix -m layers/counts --row 100 --column 20 data.h5ad

Dense, CSR, and CSC matrices are supported. Cell and variable index labels are used as row and column headers when available.

The newer commands each answer a separate single-cell question:

# How is X physically stored, and which slice direction is efficient?
adview storage data.h5ad --path X

# Which obs annotations are missing, continuous, or dominated by a few values?
adview summarize data.h5ad -g obs -c batch,cell_type --top 10

# Extract metadata using several conditions (conditions are combined with AND)
adview query data.h5ad --from obs -c _index,cell_type \
  --where batch=donor1 --where cell_type=T --limit 20

# Read only a matrix window; the complete X matrix is never materialized
adview query data.h5ad --from X --rows 100:105 --matrix-columns 20:25

# Stream global matrix statistics and per-cell/per-gene non-zero distributions
adview stats data.h5ad --matrix X

storage reports HDF5 layout, chunks, filters, logical and stored sizes, and explains the CSR/CSC access tradeoff. summarize streams table chunks and reports missingness, numeric ranges, and frequent categories. query is the unified extraction interface; head, sample, and matrix remain convenient shortcuts and compatibility commands. stats scans values in bounded chunks and includes implicit sparse zeros when calculating matrix-wide statistics.

Lightweight plots (optional)

Build the SVG plotting module when quick visual QC is useful. The plot subcommand is compiled only when the feature is enabled:

cargo build --release --features plot

# On a machine without a compatible HDF5 installation:
cargo build --release --features bundled-hdf5,plot -j 1

The plotting feature embeds kuva as a Rust library. It writes SVG directly and does not require a display server, Python, or an external plotting executable. It requires Rust 1.87 or newer; builds without --features plot retain the lighter dependency set and broader cluster compatibility.

Command	AnnData source	Purpose
`plot embedding`	`obsm/X_<basis>` plus optional `obs` field	Two-dimensional UMAP/PCA-style scatter plot
`plot counts`	One `obs` or `var` field	Bar chart of the most frequent categories
`plot distribution`	One numeric `obs` or `var` field	Histogram for a QC metric or annotation

# Read only the first two dimensions of obsm/X_umap and one obs annotation
adview plot embedding data.h5ad --basis umap --color celltype -o umap.svg

# Plot the most frequent categorical values
adview plot counts data.h5ad -g obs -c celltype --top 20 -o celltypes.svg

# Plot a numeric QC distribution
adview plot distribution data.h5ad -g obs -c gene_count --bins 40 -o genes.svg

Use adview plot --help or the help for an individual plot type to see all options:

adview plot embedding --help
adview plot counts --help
adview plot distribution --help

Embedding and distribution plots use deterministic, evenly spaced sampling when the number of cells exceeds --max-points (100,000 by default). Memory is therefore proportional to displayed points rather than the complete expression matrix. --basis umap resolves to obsm/X_umap; an explicit path such as --basis obsm/custom_embedding is also accepted. The initial plotting module uses categorical colors and SVG output. It does not load X for these plots; expression-based coloring is not yet supported.

Safely add or replace a string value under uns. Writing to a new file is the recommended default:

adview edit set-uns data.h5ad dataset_name "PBMC pilot" --output edited.h5ad

In-place editing is explicit and automatically creates data.h5ad.adview.bak before modifying the source:

adview edit set-uns data.h5ad dataset_name "PBMC pilot" --in-place

Existing output and backup files are never replaced unless --force is provided. If an in-place edit fails, adview restores the source from its backup. The former top-level set-uns spelling remains available for existing scripts.

Architecture

The AnnData semantic layer uses backend-independent encoding and selection types. Storage metadata is accessed through a small read-backend interface, currently implemented by native HDF5. This keeps query planning, validation, and editing separate from the storage engine and leaves room for Zarr and a pure-Rust HDF5 backend without rewriting the CLI commands.

head and all default to obs; use -g var (or another dataframe-like group) to inspect a different group. Output is tab-separated, so it can be piped into tools such as less, cut, and column.

Adview reads boolean, common integer and floating-point dtypes, variable-length UTF-8 and ASCII strings, categorical columns, nullable columns, and 2-D numeric arrays. Missing values are printed as NA. Unsupported nested or higher-dimensional values produce an explicit error instead of a panic.

HDF5 plugin errors

Some cluster HDF5 modules contain a build-time plugin path that does not exist on compute nodes. If an error mentions a directory such as /usr/local/hdf5/lib/plugin, override it with an existing directory:

mkdir -p "$HOME/.local/lib/hdf5/plugins"
adview --plugin-path "$HOME/.local/lib/hdf5/plugins" info data.h5ad

An empty directory is sufficient for files using compression filters built into the selected adview/HDF5 build. Other external filters—such as LZF, standalone HDF5 Zstd, or bitshuffle—require the corresponding plugin .so files in that directory. If the plugins come from the Python hdf5plugin package, its path can be found once during environment setup:

python -c 'import hdf5plugin; print(hdf5plugin.PLUGINS_PATH)'
adview --plugin-path /the/path/printed/above head data.h5ad

The equivalent environment variable works with adview and standard HDF5 tools:

export HDF5_PLUGIN_PATH=/path/to/hdf5/plugins

Contribution

code: wenjiewei

inspiration: liyang,lounan,wenhao,dingyi

License

MIT