How do you translate a Loom single-cell file guide while preserving gene rows, cell columns, graph edges and scientific labels? Loom 3.0 is an HDF5-based annotated matrix format with defined paths for matrix values, axis attributes, optional parallel layers and sparse graphs. A reliable localized explanation must preserve these structural relationships even when the surrounding prose changes language.
Searches for Loom file format explained, Loom 3.0 /matrix /row_attrs /col_attrs, Loom layers, loompy graph edges, LOOM_SPEC_VERSION, UTF-8 strings, Loom versus AnnData and single-cell gene expression metadata translation usually begin with a surprisingly basic problem: which words identify actual HDF5 objects, and which are only reader-facing descriptions? The answer controls whether a multilingual guide remains usable.
This article is a practical introduction for students, research translators, scientific data curators and software developers. It concentrates on Loom’s axis-aware storage and version behavior, rather than duplicating general HDF5 tutorials or the separate AnnData H5AD guide. The worked examples are synthetic, and all real annotations should be interpreted in their experiment context.
The short answer
Think of Loom as a matrix with an attached record of what each row and column represents. A reader must keep matrix positions, descriptive attributes, graph vertices and numeric layers aligned. Translating documentation is safe when it changes an explanatory caption; it becomes risky when it changes a structural key or moves an annotation to another recorded entity.
A first-principles way to read the file
Begin with /matrix and its N by M shape. Next inspect /row_attrs and /col_attrs, making sure that their leading dimensions follow the right axis. Then consider layers, graph relationships and the version marker. Only after the structure is understood should a glossary decide which human-facing labels can be adapted for another language.
Loom is a structured annotated matrix
Loom describes a matrix with metadata for both dimensions, often genes as rows and cells as columns in single-cell studies. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
Calling the file a spreadsheet loses the axis-aware meaning of metadata and graphs. One expression matrix can contain multiple annotations for the same cell columns. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
Read the official format specification and inspect the file hierarchy before renaming any field. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
Why HDF5 matters
Loom uses HDF5 groups and datasets, so the structure is not a set of comma-separated text tables. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
Opening a binary container in a text editor and guessing from garbled bytes misleads the reader. A visible dataset name is not the same as a text field that can be translated. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
Use an HDF5-aware viewer and distinguish groups, datasets and attributes. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
The required /matrix dataset
The specification defines a main two-dimensional dataset at /matrix with N rows and M columns. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
A caption that swaps N and M assigns gene labels to cells and vice versa. A 400-gene-by-100-cell matrix has four hundred rows and one hundred columns. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Check the matrix shape against each axis-specific annotation array. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Gene rows are a common convention
Single-cell expression Loom files often place genes on the row axis, although the data meaning follows the experiment. Reliable interpretation depends on preserving the original path, the matrix dimension to which a value belongs, and the method that produced it. A translation can simplify the wording without simplifying away those distinctions.
Assuming every row is necessarily a gene in every Loom file goes beyond the container rules. A row might represent a named feature even if its label is not an ordinary gene symbol. A neat diagram can conceal a wrong axis or a graph that has been given an unjustified biological interpretation. Readability and scientific accuracy have to be checked independently.
Explain the specific assay and check the documented row metadata. Ask a second reader to identify the same item from the translated guide. Agreement about its position and measurement is stronger evidence than agreement about vocabulary alone.
Cell columns are a common convention
Columns often represent individual captured cells or observations, with their metadata stored separately. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
Calling every column a biological replicate can overstate sample independence. Ten cells from one donor are not automatically ten independent donors. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
Determine whether columns represent cells, samples or another observation unit. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
The /row_attrs group
Row attributes attach values to rows of the main matrix in the same order. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
A translated name list sorted alphabetically can move an annotation to another gene. The label for row seven must still describe row seven after localization. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
Preserve row order and test that every row annotation has N entries on its leading dimension. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
The /col_attrs group
Column attributes attach values to matrix columns in their original order. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
Shifting a cell-label vector by one position can falsify cell clusters and sample identities. The eleventh cluster label belongs to the eleventh column, not the eleventh gene. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Compare leading lengths with M and confirm exact positional alignment. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Global attributes belong to the file
The /attrs group stores metadata that applies to the entire Loom file rather than one gene or cell. Reliable interpretation depends on preserving the original path, the matrix dimension to which a value belongs, and the method that produced it. A translation can simplify the wording without simplifying away those distinctions.
A file-level species description should not be presented as a per-cell measurement. An experiment description applies to the container unless a more specific field says otherwise. A neat diagram can conceal a wrong axis or a graph that has been given an unjustified biological interpretation. Readability and scientific accuracy have to be checked independently.
Preserve hierarchy and state the scope of each annotation in the localized glossary. Ask a second reader to identify the same item from the translated guide. Agreement about its position and measurement is stronger evidence than agreement about vocabulary alone.
The LOOM_SPEC_VERSION marker
A Loom 3.0-compliant file carries /attrs/LOOM_SPEC_VERSION identifying the specification used. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
Dropping or translating the marker name can make version-aware readers misinterpret the file. The string 3.0.0 is a format signal, not a sentence to rewrite. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
Keep the path and version value intact; translate only the explanation of what the marker does. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
Legacy versions store global attributes differently
Older Loom versions used root HDF5 attributes for globals instead of the Loom 3.0 /attrs group. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
Applying a newer path description to an older file can falsely suggest corruption. A valid older file does not become invalid merely because it lacks the newer group placement. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
Check the actual specification version before documenting or migrating global attributes. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
The optional /layers group
Additional layers may store matrices parallel to /matrix and share the same row and column dimensions. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
Calling a processed layer raw data because it has the same shape changes the measurement meaning. Raw counts and normalized values can occupy parallel matrices but are not synonymous. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Check each layer’s scientific description, numeric type and shape independently. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Layers can use different datatypes
The spec permits per-layer choices of supported numeric datatype, compression and chunking. Reliable interpretation depends on preserving the original path, the matrix dimension to which a value belongs, and the method that produced it. A translation can simplify the wording without simplifying away those distinctions.
Presenting every layer as a single numeric precision may hide rounding or storage limitations. A floating-point normalized layer should not be introduced as an integer count layer. A neat diagram can conceal a wrong axis or a graph that has been given an unjustified biological interpretation. Readability and scientific accuracy have to be checked independently.
Document datatype per layer when precision affects interpretation. Ask a second reader to identify the same item from the translated guide. Agreement about its position and measurement is stronger evidence than agreement about vocabulary alone.
Shapes are structural promises
Every additional Loom layer must conform to the main matrix’s two-dimensional shape. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
Changing feature counts or column order without adjusting associated data creates incompatible layers. An added layer with N rows and M plus one columns does not meet the stated format contract. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
Validate shape against /matrix whenever writing a conversion explanation. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
The /row_graphs group
Row graphs can encode relationships among the row entities, commonly genes or features. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
Calling a row graph a cell-neighbor network swaps the graph’s vertices. A gene coexpression graph and a cell-nearest-neighbor graph have different vertices. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
Check whether the relationship is attached to rows or columns before naming it. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
The /col_graphs group
Column graphs can encode relationships among columns, often observations or cells. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
A column graph is not inherently a spatial map or proof of biological lineage. Nearest-neighbor cells in an embedding are not necessarily directly interacting cells. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Explain what produced the edges and whether the relationship is computational or experimental. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Graph edge arrays a, b and w
Each named graph stores equally long a, b and w arrays that describe source vertices, destination vertices and weights. Reliable interpretation depends on preserving the original path, the matrix dimension to which a value belongs, and the method that produced it. A translation can simplify the wording without simplifying away those distinctions.
Translating those field keys or mixing the parallel arrays breaks graph reconstruction. Edge two uses a[2], b[2] and w[2] together, not values from different positions. A neat diagram can conceal a wrong axis or a graph that has been given an unjustified biological interpretation. Readability and scientific accuracy have to be checked independently.
Verify equal array lengths and that endpoint indices lie within the relevant dimension. Ask a second reader to identify the same item from the translated guide. Agreement about its position and measurement is stronger evidence than agreement about vocabulary alone.
Graph indices are zero-based
Loom graph vertex indices start at zero and refer to the appropriate matrix axis. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
Rewriting zero as first position without stating the index convention causes off-by-one mistakes. Vertex 0 in a column graph refers to the first matrix column. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
Explain indexing in prose while keeping stored integers unchanged. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
A graph name is not its interpretation
The name of a graph collection does not automatically define its method, metric or biological significance. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
A label such as KNN cannot by itself prove how distances were calculated or whether edges are symmetric. Two graphs both named neighbors can differ if their feature spaces or metrics differ. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
Look for the analysis method and parameters in supplementary metadata. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
Graph direction should not be assumed
Sparse edge lists identify endpoint pairs, while the semantic meaning of direction depends on the analysis. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
Treating edges as undirected when they were directed, or the reverse, can change a result. An asymmetrical edge list should not be silently mirrored for a diagram. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Record the generating algorithm and test how the receiving software interprets edges. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Row attributes can be multidimensional
The first dimension of row annotation datasets aligns with N, even when additional dimensions hold more information. Reliable interpretation depends on preserving the original path, the matrix dimension to which a value belongs, and the method that produced it. A translation can simplify the wording without simplifying away those distinctions.
Flattening several columns of annotations into one translated sentence can destroy row-wise structure. A per-gene coordinate pair is still attached to one row per gene. A neat diagram can conceal a wrong axis or a graph that has been given an unjustified biological interpretation. Readability and scientific accuracy have to be checked independently.
Validate leading dimension and explain the remaining dimensions separately. Ask a second reader to identify the same item from the translated guide. Agreement about its position and measurement is stronger evidence than agreement about vocabulary alone.
Column attributes can be multidimensional
A column attribute may hold multidimensional per-observation data with M as its leading length. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
Taking a two-coordinate embedding as two cells invents additional observations. A cell with X and Y display coordinates remains one matrix column. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
State that each cell can have a vector of attributes rather than one scalar. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
String encoding and multilingual display
Loom 3.0 uses variable-length UTF-8 strings, supporting labels outside plain ASCII. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
Confusing UTF-8 support with permission to translate stable identifiers changes the object’s identity. A translated cluster description belongs in an explanatory field, not inside an opaque cell ID. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
Keep identifier roles separate from display text, and round-trip multilingual labels. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
Older ASCII and entity encodings
Earlier Loom conventions used fixed-length ASCII strings and encoded non-ASCII characters differently. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
Directly inserting modern multilingual text into a legacy representation may produce mangled output. A visibly distorted accented name may indicate an encoding problem rather than an unknown biology term. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Check version-specific string rules and perform reversible decoding and encoding tests. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Dataset names may be API contracts
Paths such as /matrix, /row_attrs and /col_attrs are structural keys recognized by readers. Reliable interpretation depends on preserving the original path, the matrix dimension to which a value belongs, and the method that produced it. A translation can simplify the wording without simplifying away those distinctions.
Translating a path segment to another language can make a valid file unreadable. A translated heading can explain Row attributes without renaming /row_attrs. A neat diagram can conceal a wrong axis or a graph that has been given an unjustified biological interpretation. Readability and scientific accuracy have to be checked independently.
Maintain canonical structural paths and localize documentation around them. Ask a second reader to identify the same item from the translated guide. Agreement about its position and measurement is stronger evidence than agreement about vocabulary alone.
Cluster labels are analytical results
Column annotations may include clusters inferred computationally from expression or other profiles. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
A cluster number is not automatically a validated cell type or diagnostic class. Cluster 4 can be a grouping chosen by software rather than a named biological population. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
Describe the provenance of clustering and distinguish IDs from curated biological labels. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
Dimensionality reduction coordinates
PCA, t-SNE or other projections may be stored as annotation arrays linked to the relevant dimension. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
A two-dimensional plot position is not a physical tissue coordinate without specific evidence. Nearby dots in a display are evidence of an embedding, not proof of cell contact. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
State the embedding method, its parameters when known and what distance means cautiously. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
Normalization needs provenance
A Loom file may hold count data or transformed numerical values according to the producer. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
Describing every matrix element as an unmodified count can change the result materially. The value 2.3 is unlikely to be a literal count of 2.3 molecules if a transformation was applied. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Read layer names and processing documentation, checking units and transformations. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Datatype and precision affect claims
Supported integer and floating-point types can encode different ranges and numerical precision. Reliable interpretation depends on preserving the original path, the matrix dimension to which a value belongs, and the method that produced it. A translation can simplify the wording without simplifying away those distinctions.
Rounding a numerical value in a translation example may hide biologically relevant thresholds. A tiny floating-point difference may matter to exact numerical comparison even if a caption rounds it. A neat diagram can conceal a wrong axis or a graph that has been given an unjustified biological interpretation. Readability and scientific accuracy have to be checked independently.
State when numbers are illustrative and preserve original stored values for reproducible analysis. Ask a second reader to identify the same item from the translated guide. Agreement about its position and measurement is stronger evidence than agreement about vocabulary alone.
Chunking and compression are not biology
HDF5 storage strategies influence performance without normally changing the represented axes or units. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
Interpreting a chunk boundary as a biological sample boundary mistakes storage for experiment design. Reading data in blocks does not imply the cells were collected in those same blocks. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
Separate technical layout from scientific groupings in every figure and explanation. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
Metadata and privacy constraints
Cell annotations can include donor, specimen or clinical metadata with privacy and consent implications. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
Translating a field does not create new consent to disclose identifiable records. A cell ID associated with patient metadata should not be pasted into public teaching materials. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
Use synthetic examples or appropriately authorized de-identified datasets in tutorials. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
Version-aware validation
A file may be internally valid for its own Loom specification yet incompatible with a reader expecting another version. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
Calling legacy content corrupted before inspecting version creates false troubleshooting advice. Version detection should precede any change of label encoding or global attribute placement. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Confirm LOOM_SPEC_VERSION and test using a compatible reader. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Converting Loom into other containers
A conversion to AnnData or another format requires explicit handling of axes, metadata, layers and graphs. Reliable interpretation depends on preserving the original path, the matrix dimension to which a value belongs, and the method that produced it. A translation can simplify the wording without simplifying away those distinctions.
Equating a Loom row with an AnnData observation can transpose scientific entities. A gene-by-cell matrix may need a transpose for a cell-by-gene downstream object. A neat diagram can conceal a wrong axis or a graph that has been given an unjustified biological interpretation. Readability and scientific accuracy have to be checked independently.
Build an axis mapping and verify dimensions and annotations after conversion. Ask a second reader to identify the same item from the translated guide. Agreement about its position and measurement is stronger evidence than agreement about vocabulary alone.
Creating a teaching example
A small synthetic dataset is enough to demonstrate /matrix, row attributes, column attributes and graph edges. The distinction matters because an axis-aligned value is an assertion about a particular recorded entity. A reader should be able to point from the language of the explanation to the exact place in the file.
Using a real patient-derived cell atlas can create unnecessary privacy and access issues. Ask students to trace a vertex index to the right labeled matrix column. A prose sentence may sound natural and still confuse the scope of a dataset. The danger becomes visible when another person tries to trace the annotation, graph or layer back to its source.
Construct a tiny matrix, two row annotations, two column annotations and one graph edge. Use one small, constructed file as a reference for checking. It is easier to find a mismatch among five cells than among half a million observations.
A useful reader-facing glossary
A glossary should distinguish row, column, attribute, dataset, group, layer, graph and identifier. In practice, the hierarchy answers where a fact is stored while the experiment provides its scientific interpretation. Those two questions should not be compressed into an unexplained label.
Vague use of metadata as though it were a single undifferentiated block hides structural obligations. A bilingual note for /col_attrs should still tell readers that its leading dimension is M. A confident word choice is not a substitute for evidence about the axis or method. When an English label is ambiguous, keep the stable stored name and explain it plainly in surrounding prose.
Define each concept with a path, axis and small example. Write down the expected shape or index relation and inspect it after any conversion or localization. Keep the original file intact while doing the comparison.
Final checks before sharing
The localized text should allow a reader to recover exactly the same entity names, axis counts and graph endpoints. A useful guide identifies the object before discussing the words attached to it. That approach lets readers understand why a row name, cell label and file-level descriptor cannot be handled alike.
A visually attractive summary is insufficient when it cannot be checked against the file. A second reader should reproduce the same two synthetic cell annotations in each language. The most damaging mistakes are often silent: the file opens, the numbers look reasonable, and only the relationship between an annotation and its entity has changed.
Compare shapes, required groups, type rules, version marker, example row mappings and graph endpoints. Review a known example from beginning to end, tracing the field path and matrix position. If the link cannot be followed, the explanation needs correction.
Worked example: a tiny gene-by-cell matrix
Imagine three invented features and four invented cells. Give /matrix a shape of three by four, put three gene identifiers in /row_attrs and four cell labels in /col_attrs. A translated teaching diagram may change the words gene and cell, but it must not reverse their positions or change the meaning of the first row. Add a second numerical layer of exactly the same shape and describe the transformation that produced its values. The reader should be able to locate one entry in both matrices.
Worked example: a cell graph
For the same synthetic four-cell example, imagine a named /col_graphs entry with one connection recorded as a=0, b=2 and w=0.4. A faithful explanation says that the graph relates the first and third columns with the stored weight. It does not say the first and third genes are linked, nor does it claim the cells are physically touching. The meaning of the weight needs the method that produced the graph.
Frequently asked questions
Are Loom files plain text? No: they are structured HDF5 files. May I translate /row_attrs? Translate its explanation, not the canonical structural path. Can a layer have a different numeric type? Yes, while preserving required matrix shape. Are graph vertices numbered from one? No, the specification uses zero-based indexing. Is a cluster ID a verified cell type? Not by itself. How do I deal with older Loom files? Inspect version-dependent global attribute and string conventions first.
Official format documentation
Loom 3.0 format specification; HDF5 fundamentals; AnnData H5AD as a distinct format. Consult the source specification when the precise behavior of a path, data type, graph or legacy encoding matters.
Conclusion
A Loom file remains interpretable across languages when its matrix, attributes, layers and graphs still refer to the same entities. Keep exact paths and indexes intact, translate explanatory text with care, and validate a small example before trusting a larger conversion. The goal is clear language that does not alter the recorded experiment.