Export measurements to AnnData

Create an .h5ad file containing measured features and object metadata for analysis in AnnData or Scanpy. Start with a spaCR project containing measurements/measurements.db. For a worked example, download the project from the Annotate tutorial.

Export from the application

  1. From Home, open Measure, then AnnData Export.

  2. Select the measured project as the source.

  3. Set Anndata out to a new .h5ad filename. Leaving it empty writes results/<project name>.h5ad in the project folder, or results/<project name>_<table>.h5ad for a single-table export. A successful export replaces an existing file at the chosen path; use separate names to keep both versions.

  4. Set Anndata single table to cell for one row per cell using that table’s features. Use nucleus or pathogen for those object types. Leave it empty for a cell-level joined export, where child measurements are aggregated onto their parent cells.

  5. Choose Anndata nan policy, then click Run. Read the completion message and open the output file to check its shape and feature names.

Choose how to handle missing features

  • keep retains missing values. Choose this when you want to decide how to handle them in the downstream analysis.

  • drop_features removes feature columns containing missing values.

  • drop_objects removes object rows containing missing feature values.

  • mean replaces missing values with the observed feature mean. A feature with no observed values is filled with zero; that zero is an imputation, not an observed measurement.

  • zero replaces missing values with zero. Use it only when zero is an appropriate value for the intended analysis.

The imputing policies retain the original missing positions in layers['missing']. These choices apply to the feature matrix, not to unknown metadata such as unavailable calibration values. Check object and feature counts after choosing a dropping policy. Scanpy operations such as scaling and PCA need missing feature values to be handled before use.

Inspect the output

X contains the object-by-feature matrix, obs contains object metadata, and var describes the features. Keep the source images and their paths: image pixels are not embedded in the export. With the Annotate example, a cell-only export using keep has 2,341 objects, 261 features and 28 missing feature values.

obs_names retains spaCR’s object keys. Duplicate keys are refused rather than renumbered. For time-lapse data with repeated object labels across frames, use the direct Python API, for example spacr.anndata_export.export_anndata() with timelapse=True, so each frame has a distinct key.

Inspect uns['spacr'] for source tables, the run identifier, the settings hash, filters and missing-value handling. Joined child measurements are aggregated onto cells; uns['spacr']['relationships'] and var['is_aggregated'] describe those links. A single-table child export retains its parent cell_id when available.

Export from Python

The following uses the same entry point as the application’s Run button:

import anndata as ad
from spacr.anndata_export import run_anndata_export

result = run_anndata_export({
    "src": "/path/to/project",
    "anndata_out": "/path/to/project/results/cells_keep.h5ad",
    "anndata_single_table": "cell",
    "anndata_nan_policy": "keep",
})
exported = ad.read_h5ad(result.path)
print(exported.shape)
print(exported.obs.head())

For explicit function arguments, see spacr.anndata_export.export_anndata().

Object metadata columns that are entirely missing are stored as empty categorical columns in obs; no placeholder value is written. If writing a replacement fails, an existing completed output is preserved.