a•adata_science_tools
Guides About Privacy Contact
ADATA SCIENCE TOOLS

AnnData guide: prepare, analyze, reproduce

Prepare aligned AnnData inputs, choose a matrix and study design, and save reproducible analysis results.

1. Keep measurements and metadata aligned

AnnData couples a matrix X with observation metadata obs and feature metadata var. Rows represent observations, such as samples or cells; columns represent features, such as genes or proteins. Identifiers are the link between measurements and their labels—not just decoration.

For a CSV example, consider X below. Its row IDs must match obs row IDs, and its feature headers must match var row IDs. The importer aligns metadata by these IDs. Do not substitute row positions or duplicate labels for identifiers.

sample,gene_A,gene_B
sample_1,10,4
sample_2,12,7

The obs file might start sample,condition with rows sample_1,Reference and sample_2,Treatment. The var file might start feature,label with rows gene_A,A and gene_B,B. These two observations illustrate file structure only: they are not adequate replication for a group comparison.

CSV metadata initially loads as text. In the studio, explicitly choose numeric types when a metadata column is a quantitative variable. Blank cells represent missing values; examine previews and validation messages rather than assuming every value was usable. H5AD preserves additional AnnData fields that the three-file CSV bundle cannot represent.

2. Choose the matrix before choosing the test

Layers have the same shape as X and may store transformed measurements. The optional raw field is a snapshot; its name does not guarantee unprocessed counts. Check how each matrix was made. A histogram of a count matrix and a histogram of a log-transformed layer answer different questions. Do not apply a transformation twice merely because a label says “raw.”

Start in the workspace with Open demo dataset. The demo has 32 observations and 8 features, a condition column, subject IDs and a log1p layer. Choose feature_1, select the matrix source, and run a histogram. Read the axis labels and settings before moving to comparisons. The in-workspace Tutorial contains a diagram and step-by-step controls.

3. Match comparisons to the study design

Measurements from the same subject are not independent biological replicates. For the paired demo, use condition as the group column, Reference and Treatment as the groups, and subject as the pairing column when selecting a paired test. For your own study, inspect unmatched subjects, missing values and repeated measurements. A paired test is not a substitute for a model that represents a more complex design.

Effect direction depends on the selected reference and target. Review both effect estimates and uncertainty or p-values where available. A small p-value does not establish biological importance, and a non-significant result does not prove equivalence. False discovery rate correction uses the selected feature set; changing that set can change adjusted p-values. Choose and document the testing family deliberately, rather than selecting features to improve significance.

4. Save a reproducible record

In Results & downloads, inspect warnings and download the available figure, results table, analysis JSON and reproduction script. Record the input dataset version, matrix source, observation filters, selected features and method parameters. Keep those records with your original input: a figure alone cannot tell a collaborator how you produced it.

Temporary hosted datasets are eligible for cleanup after 24 hours while the worker runs. Save results promptly. In anonymous mode, browser-cookie loss or expiry also loses access, even if files have not yet been cleaned up.

References and further reading

Adapted from this project's MIT-licensed workspace tutorial and source documentation (© 2025 Benjamin M. Lewis; license). See the AnnData documentation for the data model, SciPy paired t-test documentation for assumptions, and statsmodels multiple-testing documentation for correction methods. These references explain concepts; they do not certify any uploaded analysis.

Try the synthetic demo in the workspace →