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

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

or just

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

Quick start

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

Version: 0.1.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]
  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.

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.

Contribution

code: wenjiewei

inspiration: liyang,lounan,wenhao,dingyi

License

MIT