Skip to content

CLI v0.2.0 Release Notes

Choose a tag to compare

View all tags
@Claptar Claptar released this 15 Jan 20:48
· 180 commits to main since this release
0.2.0
26591bf

h5ad CLI v0.2.0 Release Notes

Release Date: January 15, 2026

We're excited to announce a major update to the h5ad CLI tool! This release adds powerful new capabilities for working with large .h5ad (AnnData) files while maintaining the memory-efficient streaming approach you know and love.

🎉 What's New

New Command: subset - Filter Your Data

The biggest addition in this release! You can now create filtered subsets of your .h5ad files without loading them into memory.

Filter by cells (observations):

h5ad subset input.h5ad output.h5ad --obs cell_names.txt

Filter by genes (variables):

h5ad subset input.h5ad output.h5ad --var gene_names.txt

Filter by both:

h5ad subset input.h5ad output.h5ad --obs cells.txt --var genes.txt

Key Features:

  • ✅ Works with dense and sparse matrices (CSR/CSC formats)
  • ✅ Preserves all metadata and attributes
  • ✅ Memory-efficient chunked processing
  • ✅ Beautiful progress bars show you what's happening
  • ✅ Handles large files (multi-GB) with ease

Input Format:
Your cell/gene name files should contain one name per line:

AAACCTGAGAAACCAT-1
AAACCTGAGACAGACC-1
AAACCTGAGGCATGGT-1

⚠️ Breaking Changes

Table Command Arguments

We've renamed two flags in the table command for better clarity:

  • --cols → --columns (short form -c unchanged)
  • --out → --output (short form -o unchanged)

Old syntax (v0.1.x):

h5ad table data.h5ad --axis obs --cols cell_type,donor --out metadata.csv

New syntax (v0.2.0):

h5ad table data.h5ad --axis obs --columns cell_type,donor --output metadata.csv

If you're using the short forms -c and -o, your existing scripts will continue to work without changes.

✨ Improvements

Enhanced info Command

The info command now provides:

  • Better formatted output with colors
  • Clearer file structure visualization
  • More detailed group and dataset information

Example:

h5ad info data.h5ad

Improved table Command

The table export command now includes:

  • Better memory management for large files
  • Improved column validation
  • More informative error messages
  • Clearer argument names (--columns and --output)

Example:

h5ad table data.h5ad --axis obs --columns cell_type,donor --output metadata.csv

🚀 Performance & Reliability

  • Better Memory Management: All commands use chunked streaming to handle files of any size
  • Progress Feedback: Long-running operations now show progress bars
  • Error Handling: More informative error messages help you troubleshoot issues
  • Standards Compliant: Fixed encoding attributes to match h5ad specification

📦 Installation

Using uv (Recommended)

# Clone the repository
git clone <your-repo-url>
cd h5ad

# Install dependencies
uv sync

# Run commands
uv run h5ad --help

Using Docker

# Pull the latest image
docker pull quay.io/cellgeni/h5ad-cli:latest

# Run commands
docker run -v $(pwd):/data quay.io/cellgeni/h5ad-cli:latest info /data/file.h5ad

📚 Documentation

  • README: Updated with all new features and examples
  • Testing Guide: New documentation for developers at docs/TESTING.md

🔧 Technical Details

New Dependencies

  • numpy>=2.3.5 - For efficient array operations
  • rich>=14.2.0 - For beautiful terminal output

Docker Images

Images are now automatically built and published to Quay.io:

  • Tagged releases: quay.io/cellgeni/h5ad-cli:0.2.0
  • Latest stable: quay.io/cellgeni/h5ad-cli:latest
  • Preview versions: quay.io/cellgeni/h5ad-cli:0.2.0-preview3

🐛 Bug Fixes

  • Fixed encoding-type attribute to comply with h5ad standard (now writes as bytes)
  • Improved categorical data handling
  • Better sparse matrix format preservation

💡 Usage Tips

Working with Large Files

The subset command is particularly useful for:

  • Creating test datasets: Extract a small subset of cells/genes for quick testing
  • Cell type analysis: Filter specific cell populations for downstream analysis
  • Gene panel studies: Extract expression data for specific gene lists
  • Memory constraints: Reduce file size before loading into memory-intensive tools

Example Workflow

# 1. Check file structure
h5ad info large_dataset.h5ad

# 2. Export cell metadata to find interesting cells
h5ad table large_dataset.h5ad --axis obs --output cells_metadata.csv

# 3. Create a subset with specific cells (after selecting in external tool)
h5ad subset large_dataset.h5ad filtered_dataset.h5ad --obs selected_cells.txt

# 4. Verify the subset
h5ad info filtered_dataset.h5ad

🔜 Coming Soon

We're working on:

  • Additional matrix format support
  • More export options
  • Performance optimizations for very large files
  • Additional filtering options (by metadata values)

🙏 Feedback

We'd love to hear from you! If you encounter any issues or have feature requests, please:

  • Open an issue on GitHub
  • Contact the development team
  • Check the documentation for troubleshooting tips

📝 Full Changelog

See PR_DEV_TO_MAIN.md for the complete technical changelog with all 24 commits and detailed changes.

Upgrade Instructions

From v0.1.x

Update your installation:

# With uv
cd h5ad
git pull
uv sync

# With Docker
docker pull quay.io/cellgeni/h5ad-cli:latest

Update your scripts:

If you're using the table command with --cols or --out flags, update them to --columns and --output. Alternatively, use the short forms -c and -o which work in both versions.

The info command and new subset command work as documented with no migration needed.

Happy subsetting! 🎊

Assets 2
Loading