How can you translate an AnnData H5AD single-cell dataset guide without changing the cells, genes or expression values it describes? AnnData organizes a matrix of observations and variables together with annotations, alternative measurement layers and multidimensional results. In single-cell RNA sequencing, observations often represent cells and variables often represent genes or other measured features. A language editor can make the science easier to understand, but renaming the wrong identifier or changing how a category is coded can disconnect the data from its biological meaning.
Searches for AnnData H5AD format explained, obs versus var, anndata X counts or log normalized, H5AD translation, single-cell metadata localization, obsm X_umap coordinates, layers counts, raw expression matrix, sparse CSR CSC, AnnData categorical labels and scRNA-seq data conversion converge on one question: which text is a safe human-facing label, and which text is a computational key? The answer depends on how each field is used, not on whether it looks readable.
This longform educational guide explains the on-disk structure, aligned dimensions, metadata, categorical encodings, processing provenance and translation-safe validation with practical examples. It is for cell-atlas teams, translators, educators, data scientists, software developers and international research repositories. Use synthetic examples when teaching; real expression profiles and donor metadata may be sensitive. Check the official AnnData on-disk specification and the versions of the software that read or write your files.
How the AnnData object preserves scientific meaning
The one-minute explanation
An AnnData object holds a matrix X of observations by variables, metadata tables obs and var, and aligned arrays or dictionaries for additional results. In many single-cell projects, obs describes cells and var describes genes. Localize approved descriptive labels and documentation; keep observation IDs, feature IDs, numerical arrays, shapes and analysis keys stable.
Think of H5AD as the saved form of that structured object in an HDF5 file. It is not simply a spreadsheet with a hidden worksheet. Each path has a purpose, and some friendly-looking strings are referenced by other parts of the analysis.
The unit of meaning is the aligned object
An expression value becomes useful only when it is aligned to an observation and a feature. AnnData builds this alignment into its structure. If one column is a gene and one row is a cell, the corresponding entry means a measurement or derived value for that pair under the dataset’s processing definitions.
A translated chart that retains all the numbers but reorders the cell metadata independently may attach the wrong cluster, donor or sample label to each measurement. Always explain axis alignment before inviting learners to translate column descriptions or visualize the matrix.
H5AD is HDF5, not plain text
An H5AD file uses a hierarchical binary container. Its groups, datasets and attributes have structured encodings. Opening it with a word processor is not a safe way to localize names or captions. A file browser may show paths and strings, but editing them independently can violate shape and encoding relationships.
Use AnnData’s supported reading and writing API or a carefully validated format-aware workflow. If you merely need a translated report, keep the source H5AD unchanged and generate the report from it. That separation makes the data easier to audit and the language easier to revise.
The encoding-type and encoding-version attributes
AnnData’s on-disk specification uses metadata such as encoding-type and encoding-version to tell readers how an element should be interpreted. A root group may announce the AnnData encoding, while subordinate arrays, dataframes and mappings have their own conventions. These names and values are format semantics, not optional English words.
A translator can explain that an encoding version identifies how software reconstructs a stored object. They must not change the literal attribute key to a translated phrase. If an old file uses a different convention, read the documentation for the version actually written rather than assuming that every H5AD file has the latest layout.
OBS: one row per observation
The obs table contains annotations aligned to the observation axis, commonly cell-level properties in single-cell analysis. Columns might include sample, batch, inferred cell type, cluster labels, quality metrics or other study-specific metadata. The row index ties each record to the corresponding row of X.
A multilingual visualization can show ‘cell type’ in the reader’s language, but it should preserve the stable observation key and maintain the association between the metadata row and its expression measurements. Renaming a column may also break code that expects the original key, so distinguish display aliases from executable field names.
VAR: one row per measured feature
The var table aligns with the columns of X. In an RNA experiment, rows of var may represent genes and may contain identifiers, gene symbols, biotypes or quality-control information. In other AnnData applications, variables may be proteins, peaks or features with different measurement semantics.
A guide should avoid universally translating var as ‘genes’ when the dataset contains other feature types. Keep stable IDs such as Ensembl identifiers untouched. If human-readable feature names have approved localized descriptions, provide them in a companion column without replacing the identifiers used for alignment.
Observation IDs are not translated names
AnnData uses observation index values to identify rows. These may be cell barcodes, study-specific identifiers or compound keys incorporating sample names. Their punctuation and case can matter for joins. A string that looks like a normal word may still function as a unique key.
Use fictitious examples such as CELL_001 and CELL_002 to teach the concept. Translate the heading ‘cell identifier’ but not the key itself. If a repository intentionally regenerates identifiers, it needs a controlled mapping and complete validation across matrices, embeddings and metadata, not an ad hoc language edit.
Variable IDs and gene symbols are different
A stable gene identifier and a commonly used gene symbol serve related but distinct roles. Gene symbols may have historical aliases and can change with authoritative naming updates. Stable feature identifiers are often used to disambiguate sources and maintain reproducibility. Translating a symbol into a common-language phrase may destroy lookup.
In a bilingual data dictionary, preserve the original feature ID, display the recognized gene symbol where applicable and add a short local-language functional description only if supported by evidence. Be careful not to imply that the label itself establishes the biological role or clinical significance of the gene.
X does not always mean raw counts
The primary matrix X may contain raw counts, normalized values, log-transformed expression, scaled values or another representation depending on how the object was produced. An H5AD extension cannot tell you which transformation was applied. This is one of the most consequential ambiguities in teaching single-cell analysis.
A guide must ask what X means in the specific dataset and identify the relevant processing history. A value of 2.3 in a log-transformed matrix is not interchangeable with 2.3 molecules measured by a detector. Name the measurement or transformation and its units or scale before interpreting a color map.
Layers hold parallel measurements
AnnData layers can store additional two-dimensional arrays aligned to the same observations and variables as X. A project might keep counts in one layer and another processed representation elsewhere. Layer names such as counts are conventions chosen by the project, not a guarantee that the underlying values are untouched raw counts.
When localizing a tutorial, show layer keys exactly as required by the code and explain their intended meaning alongside them. Check shapes and a few values across layers. Never relabel an arbitrary transformed layer as raw merely to make a simpler diagram.
RAW retains a reference to an earlier representation
AnnData provides a raw attribute designed to keep a version of expression data and related feature annotations. It is often used to retain a reference representation while subsequent processing changes X or feature selection. This is not the same thing as a universal regulatory declaration that the data are original experimental counts.
A world-facing guide should explain the distinction between a software attribute named raw and a claim about scientific provenance. If the source contains raw, inspect its contents and creation history. Do not assume that a data structure named raw automatically contains unprocessed sequencing reads.
OBSM stores per-observation multidimensional results
The obsm mapping holds arrays or dataframes whose first dimension aligns with observations. It is often where reduced coordinates such as PCA or UMAP embeddings are stored. These numbers describe positions in a computed representation, not literal physical locations of cells inside a person.
A bilingual plot can translate axis labels, legends and explanatory text. It should not change the coordinates just to make a local-language graph look pleasing. If a new layout is computed, describe the method, parameters and seed where appropriate, and treat it as a new analysis result.
VARM is aligned to variables
The varm mapping holds multidimensional arrays aligned to the variable axis, such as gene loadings in a principal-component analysis. Its first dimension is governed by the number of variables, not the number of observations. Calling the matrix a list of cell coordinates would reverse its meaning.
Teach the difference with a simple dimension table: obsm follows n_obs, and varm follows n_vars. A guide can use different languages for the headings, but the underlying shape constraint does not change with translation. Validate the first dimension before sharing an example.
OBSP contains observation-to-observation relationships
The obsp mapping can contain square pairwise arrays aligned to observations on both axes. Single-cell workflows often use it for connectivity or distance structures. An entry is a relationship between two observation keys, which makes row and column ordering doubly important.
If cell labels are sorted or translated for a display, reordering only one axis would misrepresent the graph. Use stable IDs and a format-aware transformation when both axes genuinely need to change. Distinguish neighbor graphs from physical lineage or causal relationships unless the analysis supports that interpretation.
VARP contains variable-to-variable relationships
The varp mapping is analogous to obsp but aligned to variables on both axes. A pairwise gene or feature relationship matrix is not automatically a gene regulatory network, because its semantics depend on the calculation used to generate it. Correlation, distance and inferred regulation answer different questions.
A careful localized guide names the actual measurement and explains whether stronger numbers mean greater similarity, difference or connectivity. Preserve the feature ordering on both axes. A friendly plot legend cannot rescue an incorrectly interpreted relationship matrix.
UNS stores unstructured annotations and settings
The uns mapping can hold heterogeneous metadata, parameters, palettes, category-related settings and other objects not aligned directly to one matrix axis. Its flexibility is useful but also means that not every text string inside uns is safe to translate. Some keys are consumed by visualization or analysis libraries.
Before changing a string, identify whether it is an executable key, a categorical label, a scientific value or genuine descriptive prose. A bilingual renderer can translate user-visible descriptions while preserving software-facing keys. For archived files, record any intentional changes and validate the consuming tools.
Categorical labels are encoded, not just printed
Categorical arrays can store codes and a list of categories. A code indexes a category label, and some encodings reserve -1 for missing. The ordered flag can distinguish ordered from unordered categories. Reordering the categories list without a corresponding update to codes changes what every category code means.
Suppose code zero originally means a defined cell class. If a translated list alphabetizes the categories but leaves codes untouched, hundreds of cells may suddenly appear to have another class. Localize display labels through a stable mapping or a format-aware edit that preserves the code-to-category relationship.
Ordered categories need their sequence
Some categories have a meaningful progression such as ordered stages, while others simply name groups without ordinal ranking. An ordered categorical representation tells downstream software how levels relate. Alphabetical order in the target language is not a substitute for scientific stage order.
For a study containing developmental stages, a localized label should preserve the same sequence of stages even when their translated names alphabetize differently. A reviewer should compare both the set of categories and the ordered flag, not just whether every translated word is spelled correctly.
Missing categories are not new biological types
A categorical code such as -1 can represent missing information under the documented encoding. A translated dashboard might be tempted to replace it with ‘unknown cell type’ as though that were a confidently inferred class. The two statements are different.
Show missing annotation using a neutral label that reflects absence of an assigned category. If ‘unknown’ is an actual category in the source, distinguish it from missing values. This separation protects analyses that count unassigned cells and helps readers understand uncertainty.
Sparse CSR and CSC arrays
Large expression matrices are often sparse because many entries are zero. AnnData’s on-disk specification supports compressed sparse row and compressed sparse column encodings, with data, indices and indptr arrays and declared shape. A guide that calls those arrays a list of gene names has confused structure with annotation.
The difference between CSR and CSC concerns how sparse positions are organized for computation, not biological interpretation. Use a small grid with many zeros to explain why sparse storage is efficient, and leave the canonical encoding-type names unchanged for compatibility.
The INDICES and INDPTR arrays matter
Sparse storage uses index and pointer arrays to locate numerical values efficiently. Those arrays are not arbitrary sequences that can be sorted for readability. Reordering data, indices or indptr independently can place expression values in the wrong matrix positions or make the structure invalid.
A localized lesson can display a decoded matrix rather than raw pointer arrays. If it does teach the arrays, use a synthetic example and reconstruct the same numerical grid step by step. This demonstrates why numerical metadata must be protected as rigorously as the actual measurements.
Dataframe index and column order
AnnData’s on-disk dataframe encoding stores metadata that identifies the index and original column order. The data columns are themselves encoded arrays in a group. It can look like a collection of strings and numbers, but the layout is governed by rules that allow software to reconstruct a table.
If a translated report rearranges columns for readers, that is normally fine in the rendered report. Do not silently rewrite the stored column-order attribute or index definition. Test that obs and var can still be read with the same row keys and values.
String encoding and Unicode labels
Human-facing metadata may contain words from many languages. AnnData on-disk formats specify encodings for strings and string arrays, including Unicode-oriented handling. A translation involving accented characters or non-Latin scripts must use supported writers rather than assuming a binary byte editor can replace one string with another.
Test international characters using a synthetic dataset and round-trip them through the library. Preserve IDs whose exact bytes matter for joins, even if they appear awkward in a translated interface. An alias column can provide localized display text without changing canonical keys.
Nullable fields and their masks
Some metadata columns can contain missing integers, booleans or strings, and on-disk encodings may use masks to distinguish null from a legitimate stored value. Zero is not interchangeable with missing, and false is not interchangeable with ‘not recorded.’
A translator may need three expressions in the target language: zero, negative and unknown. A bilingual schema should preserve that distinction. Before release, check null counts in source and output and confirm that no missing-value mask was lost during conversion to a spreadsheet or a different language runtime.
Embedding coordinates do not identify cell identity
UMAP and related embeddings can create persuasive visual clusters. Those coordinates are derived from chosen algorithms, parameters and input features. They do not prove that two cells with nearby plotted points share a specific lineage, or that a translated label reflects an independently validated biological classification.
Translate cluster names cautiously, making clear when they are analyst assignments rather than ground-truth measurements. Keep embedding arrays and associated cell mapping intact. If the project relabels clusters after expert review, record the decision and the basis for the new label.
Cell types, clusters and annotations
The terms cell type, cluster, state and lineage are not synonyms. A computational cluster is a grouping under an algorithm; a cell type is a biological interpretation supported by evidence; a cell state may be transient; a lineage implies developmental or historical relationships. Translation that collapses them can overstate conclusions.
A strong annotation dictionary names the exact source field and its epistemic status. If a column is called leiden, describe it as a clustering label under a given method. If a curated cell_type field exists, attribute its authorship and evidence rather than silently upgrading the computational clusters.
Batch and donor labels must remain distinct
A batch describes a processing or experimental grouping; a donor identifies a biological source where applicable; a sample may refer to another collection unit. These labels often coexist in obs and may be used to detect technical variation or to define comparison groups. Swapping them can change the statistical model.
In a multilingual overview, use a brief glossary that shows which identifiers correspond to people, biological specimens and processing events. Do not infer a one-to-one relationship unless the study confirms it. Protect donor identity and avoid publishing combinations of metadata that make re-identification easier.
Feature annotation can have multiple vocabularies
Var metadata may contain stable gene identifiers, symbols, feature types, genomes, biotypes and other annotations. Some are controlled vocabulary terms; others are human-readable descriptions. A translation policy should classify each field before editing it rather than translating every string in one pass.
Keep identifiers such as stable database accessions exactly as supplied. For controlled terms, use authoritative multilingual equivalents where available and preserve the original code. For free prose, translate the explanation while retaining provenance and any uncertainty expressed by the source.
Spatial data may add further conventions
An AnnData object can be used in spatial biology, and related tooling may place spatial coordinates or image metadata in established keys. Those conventions are not guaranteed by the generic H5AD container alone. A coordinate pair can refer to pixels, physical dimensions or another frame depending on the associated workflow.
A localized guide must identify the coordinate frame and units before interpreting a plotted position. Do not treat image pixel positions as anatomical millimetres without a documented transformation. Preserve links and keys required by the spatial reader, and keep geometric measurements separate from narrative labels.
Slicing observations changes aligned data
AnnData supports slicing along observations and variables while preserving alignment of appropriate attributes. Selecting a subset of cells is a computational operation, not merely hiding rows in a translated report. Certain stored references such as raw may have different retention behavior from X under variable selection.
When teaching filtering, explicitly say whether the source object was only viewed or a new subset was created. Record the number of observations and variables before and after. This prevents a reader from interpreting a smaller plot as evidence that biological cells vanished from the original experiment.
Concatenation and category collisions
Combining AnnData objects requires care with observation IDs, feature sets, batch indicators, annotation columns and missing values. Two laboratories may use the same short cell barcode in different samples; joining on the barcode alone could create collisions. Translated cell-type labels may also appear to conflict with controlled source categories.
Before merging, define the stable joint identity and harmonization rules. Keep original dataset provenance and ensure that identical-looking translated labels genuinely refer to comparable definitions. A combined atlas should document how conflicts and missing features were resolved rather than concealing them.
H5AD and Zarr share concepts but not storage
AnnData can be serialized into HDF5-based H5AD and Zarr-based stores with similar higher-level concepts. They are not identical physical containers. Zarr chunks and store layouts involve different operational considerations from HDF5 file handling. Changing an extension cannot convert one into the other.
For a world-facing guide, distinguish the AnnData object model from its storage backend. Use an appropriate writer for conversion, and then validate the same shapes, keys, matrix values, categories and aligned attributes. Any differences in supported encodings must be handled through documented library behavior.
Backed mode and partial loading
Large H5AD files may be read in backed or partially loaded modes to manage memory. A user could see metadata in memory while numerical data remain on disk. A translation script that assumes the whole file is a mutable text object may fail or write incomplete changes.
Design the workflow around the library’s documented reading and writing capabilities. Make a controlled output copy rather than overwriting an authoritative source. Validate the saved file by reopening it, inspecting shapes and confirming several data values and annotations.
File size and compression are not data quality
H5AD storage can use compression and sparse representations to reduce size. A much smaller file does not necessarily contain less biological information, but it can if the process intentionally discards layers, features or precision. File size alone is not an adequate integrity test.
Use shape comparisons, matrix summaries, category sets and provenance records to establish what survived a conversion. Explain any lossy step explicitly. Avoid telling readers that a compressed or normalized single-cell file is ‘better quality’ solely because it occupies fewer bytes.
Provenance and processing history
A reproducible single-cell analysis needs information about read processing, count generation, quality control, filtering, normalization, feature selection, batch handling and analytical methods. Some of this may live in uns, obs, var or external records; not every H5AD contains a complete processing log.
A good localized data dictionary names what is known and what is not. If a metadata field says ‘normalized,’ identify the method if the record supplies it. Do not fill missing steps from common practice and then present them as facts about this particular dataset.
Privacy and research consent
A single-cell dataset may contain donor identifiers, disease status, demographic attributes or detailed sample histories. Even when observations are individual cells, metadata can connect them to identifiable participants. Public translation work should normally use sanitized metadata and synthetic matrices.
Follow applicable institutional approvals and data-protection requirements. Limit access to raw files, remove unnecessary identifying information from public examples and provide authorized explanations of consent restrictions. The fact that a cell barcode looks anonymous does not establish that the larger dataset is safe to publish.
A robust bilingual annotation dictionary
The dictionary should have the canonical path or key, its scientific meaning, its type and shape, allowed values, translation policy, a target-language display label and an example. Put stable IDs and controlled codes in a preserve-exactly category; put authorized free descriptions in a translatable category.
Add a column for reviewer notes when terminology is disputed. If a computational field is called X_umap, preserve the key and describe its mathematical role in the target language. For a cell-type category, retain the mapping from original values to localized labels so analyses remain reproducible.
Validate the complete object, not a screenshot
A screenshot can conceal missing values, show rounded expression, sort category labels and truncate metadata names. A full AnnData validation checks shapes, unique index expectations, aligned arrays, category codes and numerical values after reading the saved file. It must also examine the translated explanations for scientific fidelity.
Use a synthetic fixture with distinct observation IDs, several feature IDs, a sparse matrix, a categorical missing value, one layer, a two-dimensional embedding and a pairwise matrix. A round-trip test with target-language display labels should prove that the source numbers and keys are still available unchanged.
When a field name becomes part of code
Many analysis scripts refer to obs columns, layer keys and embedding names using exact strings. Replacing ‘cell_type’ with a translated phrase inside the stored object may break a plot function even if the biology is unchanged. Conversely, keeping every field name in English does not prevent a reader from receiving a fully localized guide.
Prefer a presentation layer or explicit alias mapping. If the application requires stored localized keys, update consumers through a controlled interface migration and validate behavior. That is software maintenance with scientific consequences, not a simple editorial find-and-replace job.
Prepare a release that others can reproduce
Record the originating dataset, permitted purpose, AnnData and dependent library versions, original file checksum, shapes, metadata dictionary, transformations and review results. Preserve an untouched source copy when authorized. A localized release should say precisely whether it changed only documentation or also produced a derived H5AD.
A multilingual handoff is successful when an independent researcher can read the technical keys, reconstruct the biological meaning and distinguish original evidence from new interpretation. A transparent change log creates that trust without forcing every reader to understand the full binary encoding.
Twelve worked biological-data localization cases
The counts layer is mistaken for log expression
A visualization guide labels X as raw read counts because a layer named counts exists. In the actual file, X contains log-normalized values. The corrected guide states where counts reside and how X was derived, citing the dataset’s processing record. It also warns that numerical values in those two matrices answer different questions.
Cell metadata are sorted but the matrix is not
A localizer alphabetizes obs rows using translated cell-type names, then exports the original X unchanged. Expression values are now shown beside the wrong cells. The fix is to preserve original alignment or to reorder the object through AnnData-aware operations that transform all relevant components together. Validate several cell-by-feature entries.
Gene symbols replace stable identifiers
An editor overwrites stable feature IDs with friendly names in another language. Duplicate names appear and external joins fail. A better release keeps original var identifiers and adds separate descriptive labels with traceable source references. Readers gain context without losing the keys needed for computation.
The categories array is alphabetized
A categorical field stores code 0 for one cell class and code 1 for another. The translated list is sorted in a new order while codes remain the same. Most labels are now attached to the wrong cells. Preserve the code-to-category mapping or perform a validated format-aware recoding, then compare per-class counts.
The missing code becomes a new cell type
A category has a missing code of -1. A dashboard translates it into a named biological state as if the analysis identified one. The corrected view distinguishes unassigned or unavailable information from a defined category. Reviewers check null counts before and after localization and ensure no source annotation was invented.
A UMAP figure is treated as tissue geography
A bilingual article calls an obsm X_umap coordinate the physical position of a cell in tissue. UMAP is a computed representation and usually does not encode that physical location. Translate the axis explanation accurately and separate embedding plots from spatial-coordinate data when a spatial assay is involved.
A pairwise graph loses an axis alignment
An analyst changes row labels of an obsp connectivity matrix but not its column mapping. Relationships seem to move between cells. The corrected workflow uses stable observation keys on both axes and verifies representative edges. A color legend cannot compensate for an inconsistent square matrix.
A feature subset changes what raw retains
A tutorial assumes that selecting ten genes makes every attribute, including raw, automatically contain only those genes. The actual AnnData behavior may retain a broader raw representation. A good guide explicitly inspects X, var, raw.X and raw.var after the operation rather than extrapolating from the smaller visible plot.
A compressed sparse matrix is edited as dense text
A translator tries to alter labels by manually editing HDF5 groups holding CSR data, indices and indptr arrays. The resulting file no longer loads correctly. The safe workflow uses a compatible library for any authorized metadata work, protects numerical arrays and verifies the reconstructed matrix after saving.
Donor and sample are conflated
A public plot uses a sample ID as though it identified a unique human donor, but a donor contributed several samples. The local-language explanation now misstates the study design. Restore the actual mapping and define donor, specimen, sample, library and cell as different possible collection units.
A cross-laboratory atlas merges aliases wrongly
Two laboratories label an inferred state with slightly different source terms. Translation makes both labels sound identical, so a curator merges them without validation. The proper response is to compare definitions, markers, method and evidence, then create a documented harmonization decision if supported. Translation alone cannot prove biological equivalence.
A reproducible international handoff
A team publishes a translated single-cell tutorial using synthetic H5AD data with X, obs, var, layers, obsm and a categorical annotation. The original scientific keys remain intact; target-language display labels live in the guide. Reviewers round-trip the data, verify dimensions and check missingness. The tutorial works in multiple languages without exposing donor metadata or changing the measurements.
A practical twenty-step H5AD review checklist
- Confirm the file was written as AnnData H5AD, not generic HDF5.
- Check the root encoding-type and encoding-version.
- Record the number of observations and variables.
- Confirm X meaning and transformation status.
- Preserve observation index keys and row alignment.
- Preserve feature index keys and column alignment.
- Inspect all present layers and their shapes.
- Document the provenance of any counts layer.
- Inspect raw.X and raw.var rather than assuming contents.
- Preserve obsm observation alignment.
- Preserve varm variable alignment.
- Check obsp and varp square axes.
- Inspect uns keys used by code.
- Validate categorical codes and category ordering.
- Preserve missing values, including categorical missing codes.
- Validate CSR or CSC sparse matrix reconstruction.
- Round-trip non-Latin display labels where supported.
- Compare representative numeric values and metadata.
- Protect donor-sensitive annotations and permissions.
- Record versions, transformations, reviewers and checksums.
Frequently asked AnnData and H5AD questions
Does X always contain raw RNA counts?
No. The meaning of X depends on the dataset and processing pipeline. It may hold counts, normalized or transformed values, or another matrix representation.
What is the difference between obs and var?
Obs describes observations, often cells, aligned to rows. Var describes features, often genes, aligned to columns. The actual biological meaning must be checked against the dataset.
Can I translate obs and var keys?
Keep computational keys stable unless a documented interface migration updates every consumer. Translate explanations and display aliases separately.
Are H5AD and HDF5 the same thing?
H5AD is an AnnData-specific HDF5 serialization with prescribed object structure and metadata. A generic HDF5 file is not automatically a valid AnnData object.
What do layers contain?
Additional matrices aligned to the observation and variable axes. Their names and scientific meanings depend on the project; do not infer that a layer is raw merely from a friendly label.
What does obsm X_umap mean?
Usually an observation-aligned computed embedding. Its coordinates do not automatically refer to physical locations or causal relationships.
Why are category codes important?
They map numeric codes to category labels. Changing category order without updating codes can reassign annotations to the wrong cells.
Can I change gene symbols to another language?
Keep stable gene IDs and recognized symbols as source identifiers. Add authorized localized descriptions in a separate field or display layer.
What is an H5AD round-trip test?
Read a file, write it through a compatible library, reopen it and compare shapes, keys, important metadata, categories and representative numerical values.
Can I publish donor metadata from an H5AD file?
Only when the approved data-use terms, consent conditions and applicable law permit it. Use synthetic or appropriately controlled examples in educational material.
Conclusion: the atlas remains reproducible
AnnData is useful because it keeps measurements, observation annotations, feature annotations and analytical results together in a coherent aligned object. Translation should provide that coherence to human readers, not destroy it inside the file. Preserve canonical keys and numeric values, explain the difference between raw measurements and derived representations, and verify that categories still refer to the same cells after any approved localization work.
The strongest bilingual release combines a protected source object, a human-readable data dictionary and a documented review path. It tells readers which labels they may translate, which keys software needs unchanged and which biological interpretations remain uncertain. That is the foundation of responsible international data communication: a reader can learn in their language while another researcher can still reproduce the original result.
Official references and related reading
- AnnData on-disk format specification — groups, arrays, sparse encodings, categories and dataframes.
- AnnData object API documentation — X, obs, var, layers, obsm, varm, obsp and varp.
- AnnData reading and writing APIs — H5AD and Zarr interoperability.
- Translate Like a Pro: HDF5 — underlying container concepts.
- Translate Like a Pro: Matrix Market MTX — a separate sparse-matrix exchange format.