h5mu-structure

name

h5mu-structure

description

Inspect an .h5mu (MuData) file and generate a structured txt summary of its contents in a tree format. Lists all modalities, their X matrices, obs/var columns, uns, obsm, layers, obsp, varm, varp, and MuData-level attributes. Use this skill whenever the user asks to inspect, describe, summarize, or explore the structure of a .h5mu file, or when they want to know what's inside a MuData object saved on disk. Also trigger when the user says things like "what's in this h5mu", "show me the structure", "list the columns", "describe this mudata", or references .h5mu files and wants to understand their contents.

h5mu Structure Inspector

When the user wants to inspect or summarize the structure of an .h5mu file, run the bundled Python script to generate a detailed tree-format summary.

How to use

1. Identify the .h5mu file path the user wants to inspect.
2. Run the inspection script:

python3 SKILL_DIR/scripts/inspect_h5mu.py <path_to_file.h5mu>

Replace SKILL_DIR with the actual path to this skill's directory (where this SKILL.md lives).

3. The script writes <filename>_structure.txt in the same directory as the input file and also prints the output to stdout.

4. Share the key findings with the user — modalities found, shapes, notable obs/var columns, what's stored in uns/obsm, etc.

What the output contains

For each modality in the MuData:

• X: matrix type (sparse/dense), shape, dtype
• obs/: all column names, with example obs_names (cell barcodes); each column annotated with its dtype/cardinality and 3 example values from the first 3 cells
• var/: all column names, with example var_names (gene IDs); each column annotated with its dtype/cardinality and 3 example values from the first 3 genes
• uns/: each key with its type, shape, and example values
• obsm/: each key with type and shape (e.g., guide_assignment, X_PCA, X_umap)
• layers/, obsp/, varm/, varp/: listed if non-empty

Plus a MuData-level section showing merged obs/var columns (with 3 example values per column) and top-level obsm/uns/etc.

Column annotation format

Each obs/var column line looks like:

├── <col_name> — <dtype>: e.g. <v1>, <v2>, <v3>

For categorical columns, the cardinality and first 3 categories are also shown:

├── batch — categorical[26] cats: 'IGVFDS6990PWDJ', 'IGVFDS7696ONVJ', 'IGVFDS3...' | e.g. 'IGVFDS6990PWDJ', 'IGVFDS7696ONVJ', 'IGVFDS6990PWDJ'

Requirements

• Python 3 with muon, anndata, numpy, scipy installed
• The environment on Stanford Sherlock HPC already has these available

Example output

cNMF_5_0_2.h5mu Structure
=========================
Type: MuData
Modalities: ['rna', 'cNMF']
Total cells (obs): 91866

================================================================================
Modality: rna
================================================================================
Shape: (91866 cells, 9397 variables)

├── X (sparse csr_matrix, shape=(91866, 9397), dtype=float32)
├── obs/ (91866 observations)
│   ├── obs_names: e.g. CGTTCTGCAGCGATCC_0, ATAACGCCATGCCTTC_0, GACACGCTCGTCCGTT_0
│   ├── batch — categorical[26] cats: 'IGVFDS6990PWDJ', 'IGVFDS7696ONVJ', 'IGVFDS3...' | e.g. 'IGVFDS6990PWDJ', 'IGVFDS7696ONVJ', 'IGVFDS6990PWDJ'
│   ├── n_counts — int32: e.g. 2713, 1773, 5421
│   └── ...
├── var/ (9397 variables)
│   ├── var_names: e.g. ENSG00000230021, ENSG00000228794, SAMD11
│   ├── symbol — object: e.g. 'LINC01128', 'SAMD11', 'NOC2L'
│   └── ...
├── uns/
│   ├── guide_names (ndarray, shape=(416,), ...)
│   └── guide_targets (ndarray, shape=(416,), ...)
├── obsm/
│   └── guide_assignment (sparse csr_matrix, shape=(91866, 416))
...