<LinkableSection id={"overview"} title={"Overview"}>

On this page, we provide a few resources with example code from commonly used software packages to help you start exploring several Atera Onboard Analysis output files.

<SupportCallout level={"info"}>10x Genomics does not provide support for community-developed tools and makes no guarantees regarding their function or performance. For questions about these tools, please contact tool developers.</SupportCallout>

</LinkableSection>

<LinkableSection id={"r-env"} title={"Working with files in R"}>

If you are working with Atera data in an **R programming environment**, there are several tools available for working with Atera image, cell, and transcript data.

The example below illustrates data analysis use cases with [Seurat](https://satijalab.org/seurat) tools. The function to load Atera data has been optimized for lazy loading and can be run from a desktop computer (recommended specs to process an entire slide of Atera data: 1 TB disk space, SSD hard drive).

- [Loading and visualizing 10x Atera data tutorial](https://satijalab.org/seurat/articles/atera_tutorial)

</LinkableSection>

<LinkableSection id={"py-env"} title={"Working with files in Python"}>

If you are working with Atera data in a **Python programming environment**, there are several tools available for working with Atera image, cell, and transcript data. The examples below illustrate a few of these use cases.

</LinkableSection>

<LinkableSection id={"spatialdata-examples"} title={"Analyze Atera data with spatialdata-io"} nested={true}>

The [SpatialData](https://spatialdata.scverse.org/projects/io/en/latest) tools function to load Atera data has been optimized for lazy loading and can be run from a desktop computer (recommended specs to process an entire slide of Atera data: 1 TB disk space, SSD hard drive). A demo is provided in [this Jupyter notebook](https://github.com/10XGenomics/spatialdata-io/blob/atera-reader/notebooks/atera_example.ipynb) to showcase setting up the computing environment, loading the data, and a few use cases.

</LinkableSection>

<LinkableSection id={"zarr2pq"} title={"Convert Zarr to parquet format"} nested={true}>

We highly recommend working with the Zarr file format itself. However, if the Parquet format is needed (e.g., for a third-party tool, such as Proseg), the example below demonstrates how to use Python to convert the `transcripts.zarr.zip` file to `transcripts.parquet` format. For larger datasets, you may encounter memory limits for reading and converting the data to Parquet.

```python language="python"
# Use the atera_to_parquet function
from spatialdata_io import atera_to_parquet

# Convert the Atera transcript Zarr bundle into a Parquet file
atera_to_parquet(
    path="path/to/atera_dataset",
    output="path/to/transcripts.parquet"
)
```

</LinkableSection>

<LinkableSection id={"view-imgs"} title={"View multi-file OME-TIFF images"} nested={true}>

[Multi-file OME-TIFF images](/support/software/atera-onboard-analysis/latest/analysis/output-understanding-outputs#images) can be viewed with the commonly used Python package, [Tifffile](https://pypi.org/project/tifffile). However, it does not open downsampled multi-file images by default. Downsampled images may be useful for converting to other image file types or for viewing the image if the full resolution is too large. The code snippet below illustrates how to open either full or downsampled resolution images.

To open all of the multi-tissue stain images together, all four `ch<number>_<stain name>.ome.tif` files must be present in the `morphology_2d/` directory.

```python language="python"
# Import Python libraries
# This code uses python v3.14.6, tifffile v2026.6.1, matplotlib v3.11.0
import tifffile
import matplotlib.pyplot as plt

# Edit path to file
filename="morphology_2d/ch0000_dapi.ome.tif"

# This function prints out the resolution levels and shape of each pyramid in the image file.
with tifffile.TiffFile(filename) as tif:
    series = tif.series[0]
    print("Number of levels:", len(series.levels))
    for idx, level in enumerate(series.levels):
        print(f"Level {idx}: shape={level.shape}, dtype={level.dtype}")

# Option 1: Load full resolution image channels
# The following may produce a warning: 'OME series cannot read multi-file pyramids'. This is because tifffile does not support loading a pyramidal multi-file OME-TIFF file. Only the full resolution (level=0) data will load for all channels in the directory.
fullres_multich_img = tifffile.imread(
filename, is_ome=True, level=0, aszarr=False)

# Examine shape of array (number of channels, height, width), e.g. (4, 40867, 31318)
fullres_multich_img.shape

# Extract number of channels, e.g. 4
n_ch = fullres_multich_img.shape[0]

# Plot each channel
fig, axes = plt.subplots(ncols=n_ch, nrows=1, squeeze=False)
for i in range(n_ch):
    axes[0, i].imshow(fullres_multich_img[i], cmap="gray")
    axes[0, i].set_title(f"Channel: {i}")
plt.savefig('tifffile_fullres_four_channels.png')

# Option 2: Load a single channel image at any resolution, e.g., level=0 or level=1. Note 'is_ome' is set to False.
# Load one of the multi-file OME-TIFF files as a regular TIFF file at full resolution.
fullres_img_tiff = tifffile.imread(filename, is_ome=False, level=0)

# Now load the file at downsampled resolution
downsampled_img = tifffile.imread(filename, is_ome=False, level=1)
# Examine shape of array (number of channels, height, width)
downsampled_img.shape

# Plot the full resolution and downsampled images side-by-side
fig, axes = plt.subplots(ncols=2, nrows=1, squeeze=False)
axes[0, 0].imshow(fullres_img_tiff, cmap="gray")
axes[0, 0].set_title(f"Full resolution: {fullres_img_tiff.shape}")
axes[0, 1].imshow(downsampled_img, cmap="gray")
axes[0, 1].set_title(f"Downsampled: {downsampled_img.shape}")
plt.savefig('example_fullres_downsample.png')
```

</LinkableSection>

<LinkableSection id={"zarr-cell-mask"} title={"Extract cell segmentation mask"} nested={true}>

The `zarr` Python library documentation and tutorials are available [here](https://zarr.readthedocs.io/en/stable/tutorial.html). These code snippets below show how to read a Zarr array into `numpy` [N-dimensional arrays](https://numpy.org/doc/stable/reference/arrays.ndarray.html). This code can be used to explore any of the Atera Onboard Analysis [Zarr output files](/support/software/atera-onboard-analysis/latest/analysis/output-zarr-landing).

Read in the `cells.zarr.zip` file and take a look at the file's structure:

```python language="python"
# Import Python libraries
# This script has been tested with zarr v2.13.6, v2.18.3, v3.0.5, v3.2.1
import zarr
import numpy as np

# Function to open a Zarr file
def open_zarr(path: str) -> zarr.Group:
    store = (
        zarr.storage.ZipStore(path, mode="r") if path.endswith(".zip")
        else zarr.storage.LocalStore(path)
    )
    return zarr.open_group(store=store, mode="r")

# For example, use the above function to open the cells Zarr file, which contains segmentation mask Zarr arrays
root = open_zarr("cells.zarr.zip")

# Look at group array info and structure
root.info
root.tree() # shows structure, array dimensions, data types

# Create cell and nucleus segmentation mask np array objects to read or modify
root['masks'].tree()
cellseg_mask = np.array(root["masks"]["1"])
nucseg_mask = np.array(root["masks"]["0"])

# Show dimensions of the 2D segmentation mask arrays (also shown in .tree())
# .ndim() shows number of dimensions
# The shape should match the number of pixels in the morphology image.
cellseg_mask.shape
nucseg_mask.shape

# Show max value of cells in the masks (value=0 are background pixels)
# The .max() method counts all the values that are not 0, which should equal
# the total cells detected in the dataset (reported in e.g., analysis_summary.html
# summary tab metric).
cellseg_mask.max()
nucseg_mask.max()

# Examples for exploring file contents
# How to show array
root["masks"]["0"][0:9] # or root["masks/0"]
root["cell_summary"][0:9]
# How to list out attribute names and values
dict(root.attrs.items())
dict(root['cell_summary'].attrs.items())
# How to show attribute values
root.attrs["major_version"]
root.attrs["segmentation_methods"]
```

</LinkableSection>

<LinkableSection id={"config-json"} title={"Parse panel JSON file"} nested={true}>

Python or other tools can be used to parse the [panel configuration JSON file](/support/software/atera-onboard-analysis/latest/analysis/output-understanding-outputs#panel). Here is example Python code to extract gene name, Ensembl ID, and gene coverage information for each gene target in a given panel:

```python language="python"
# Import Python libraries
# Example with python v3.14.6, pandas v3.0.3
import json
import pandas as pd

# Open JSON file
f = open('panel_config.json') # Edit file name here

# Return JSON object as a dictionary
data = json.load(f)

# Create lists to store extracted information
gene = []
ensembl = []
cov = []
# Iterate through the JSON list to extract information
payloads = data.get('payloads', [])
if isinstance(payloads, dict):
    payloads = [payloads]

for payload in payloads:
    for i in payload.get('targets', []):
        if i['type']['descriptor'] == "gene":
            gene_name = i['type']['data']['name']
            ensembl_id = i['type']['data']['id']
            coverage = str(i['info']['gene_coverage'])

            gene.append(gene_name)
            ensembl.append(ensembl_id)
            cov.append(coverage)

# Create output CSV file
out_df = pd.DataFrame(list(zip(gene, ensembl, cov)), columns=['Gene name', 'Ensembl ID', 'Gene coverage'])
out_df.to_csv('my_panel_gene_info.csv', index=False)

# Close file
f.close()
```

</LinkableSection>


Overview

Working with files in R

Working with files in Python

Analyze Atera data with spatialdata-io

Convert Zarr to parquet format

View multi-file OME-TIFF images

Extract cell segmentation mask

Parse panel JSON file

Code examples

Atera Instrument Software enables run set up, Atera Onboard Analysis data generation, and data egress.

Atera Onboard Analysis

Atera

Example Code for Working with Atera Outputs

<LinkableSection id={"metadata"} title={"Field descriptions"}>

The `experiment.spatial` file is an output from the Atera Onboard Analysis pipeline. The metadata fields in this file are described below, grouped by the fields pertaining to instrument run and panel configuration, analysis metrics, and output files.

</LinkableSection>

<LinkableSection id={"metadata-instr"} title={"Instrument run and panel config fields"} nested={true}>

| Field                                           | Description                                                                                                                                                                          |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `major_version`                                 | Indicates major version of analysis output file formats. Used by other software to check compatibility.                                                                            |
| `minor_version`                                 | Indicates minor version of analysis output file formats. Used by other software to check compatibility.                                                                            |
| `run_name`                                      | User-specified analysis run name on instrument                                                                                                                                     |
| `run_start_time`                                | Instrument run start time                                                                                                                                                          |
| `slide_name`                                    | User-specified slide name on instrument                                                                                                                                            |
| `slide_id`                                      | User-specified slide ID (optional) on instrument                                                                                                                                   |
| `region_name`                                   | User-specified region name on instrument                                                                                                                                          |
| `slide_type`                                    | Slide type used on instrument                                                                                                                                                     |
| `sample_type`                                   | User-specified sample preservation method                                                                                                                                         |
| `panel_config`                                  | Specifies the name and ID of the panel configuration                                                                                                                                             |
| `panel_[...]`                                     | For each panel in the panel configuration (possible fields: `panel_WTA`, `panel_a`, `panel_c`), specifies panel name, panel design ID, number of targets, organism, and tissue type                                                               |
| `total_num_targets`                             | Total number of unique targets in the panel configuration                                                                                                                       |
| `segmentation_stain`                            | The segmentation stain method ("atera_cell_segmentation_stains_v1" or "atera_dapi_18s_only_v1")                                                                               |
| `chemistry_version`                             | Assay chemistry specified by the `panel_config.json` file ("Atera v1")                                                                                                           |
| `pixel_size`                                    | Pixel size in the `morphology_3d/ch0000_dapi_3d.ome.tif` image file (in µm)                                                                                                        |
| `z_step_size`                                   | Z-step size (in &micro;m) used for subsampling the `morphology_3d/ch0000_dapi_3d.ome.tif` image Z-stacks                                                                                |
| `instrument_sn`                                 | Atera Instrument serial number                                                                                                                                                 |
| `instrument_sw_version`                         | Version of the Atera Instrument firmware used during analysis run                                                                                                                 |
| `analysis_sw_version`                           | Version of Atera Onboard Analysis pipeline used to analyze data                                                                                                                   |
| `analysis_uuid`                                 | Instrument metadata                                                                                                                                                              |
| `experiment_uuid`                               | Instrument metadata                                                                                                                                                              |
| `cassette_uuid`                                 | Instrument metadata                                                                                                                                                              |
| `roi_uuid`                                      | Instrument metadata                                                                                                                                                              |
| `well_uuid`                                     | Instrument metadata                                                                                                                                                              |
| `calibration_uuid`                              | Instrument metadata                                                                                                                                                              |

</LinkableSection>

<LinkableSection id={"metadata-aoa"} title={"Atera Onboard Analysis pipeline metrics"} nested={true}>

| Field                                           | Description                                                                                                                                                                          |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `num_cells`                                     | Cells detected                                                                                                                                                                       |
| `transcripts_per_cell`                          | Median transcripts per cell                                                                                                                                                        |
| `genes_per_cell`                                | Median genes per cell                                                                                                                                                              |
| `nuclear_transcripts_per_100um`                 | Number of high-quality, decoded-to-gene nuclear transcripts divided by the total segmented nuclear area                                                                             |
| `transcripts_per_100um`                         | Transcripts per 100 &micro;m2                                                                                                                                                            |
| `num_transcripts`                               | Total number of transcripts including low-quality transcripts                                                                                                                       |
| `num_transcripts_high_quality`                  | Total high quality decoded transcripts (≥ Q20)                                                                                                                                      |
| `region_area`                                   | Total area of imaged field of views (FOVs)                                                                                                                                        |
| `total_cell_area`                               | Summed area of detected cells                                                                                                                                                      |
| `thickness_of_high_quality_decoded_transcripts` | Width in Z of high-quality transcripts measured in microns                                                                                                                          |
| `non_zero_matrix_entries`                       | Number of nonzero entries in the sparse CSC cell-feature matrix in the `csc_cell_feature_matrix.zarr.zip` file                                                                     |
| `fraction_transcripts_assigned`                 | Percent of high-quality transcripts that are found within cells                                                                                                                    |
| `segmented_cell_stain_frac`                     | Sum of `segmented_cell_boundary_frac` and `segmented_cell_interior_frac`                                                                                                               |
| `segmented_cell_boundary_frac`                  | Fraction of cells where the cell segmentation boundary is derived from the boundary stain                                                                                         |
| `segmented_cell_interior_frac`                  | Fraction of cells where the boundary is from expansion of the nucleus using interior stain information                                                                             |
| `segmented_cell_nuc_expansion_frac`             | Fraction of cells where the boundary is an isotropic expansion from the nucleus boundary                                                                                          |
| `segmented_nucleus_focus_frac`                  | Fraction of nuclei that were segmented from focus images                                                                                                                          |
| `segmented_nucleus_focus_count`                 | Number of nuclei that were segmented from focus images                                                                                                                            |
| `segmented_nucleus_zstack_frac`                 | Fraction of nuclei that were segmented from Z-stack images                                                                                                                        |
| `segmented_nucleus_zstack_count`                | Number of nuclei that were segmented from Z-stack images                                                                                                                          |
| `cell_types`                                    | Cell type annotation categories (coarse, fine)                                                                                                                                     |


</LinkableSection>

<LinkableSection id={"metadata-explorer"} title={"Output fields read by 10x Explorer"} nested={true}>

| Field                                           | Description                                                                                                                                                                          |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `images`                                        | Specifies the file paths to the 3D and 2D morphology image files                                                                                                                    |
| `explorer_files`                                | Specifies the file paths to cell, transcript, cell-feature matrix and secondary analysis, and analysis summary files                                                                                       |

</LinkableSection>

<LinkableSection id={"expt-file-versions"} title={"Experiment file versions"}>

The `major_version` field in this file indicates when there are changes to Atera Onboard Analysis output file formats that affect forwards-compatibility with other software.

Updates to `major_version` are associated with new releases of the Atera Onboard Analysis software on the Atera Instrument. For example, this format version is used by [10x Explorer](/support/software/tenx-explorer/latest) to determine input file compatibility across the 10x in situ software suite. This table tracks the Atera Onboard Analysis software version that introduced each file format major version.

| Atera Onboard Analysis version | `experiment.spatial` major version |
| --------------- | --------------------------------- |
| v1.0 | 1.2 |

</LinkableSection>


Field descriptions

Instrument run and panel config fields

Atera Onboard Analysis pipeline metrics

Output fields read by 10x Explorer

Experiment file versions

Experiment File

Atera Experiment File Metadata and Versions

<LinkableSection id={"decoding-metric-calc"} title={"Negative control metrics"}>

The [Atera Onboard Analysis output files](/support/software/atera-onboard-analysis/latest/analysis/output-understanding-outputs) `analysis_summary.html` and `metrics_summary.csv` report negative control metrics.

The "Negative control probe counts per control per cell" metric is derived in two steps. First, calculate the absolute number of negative control probe counts. Then, calculate the metric per control probe per cell. The "Estimated number of false positive transcripts per cell" is derived from this metric. Derived values may differ slightly from those reported in summary outputs due to using rounded values.

They are calculated using the following inputs:

- Total high quality decoded transcripts: displayed on the Summary and Decoding tabs, includes genes (Q-Score ≥ 20) and negative controls
- Percent of transcripts within cells: displayed on the Cell Segmentation tab
- **Adjusted negative control probe rate**: displayed on the Decoding tab
- Number of target genes: the sum of genes in the pre-designed panel and any custom genes, displayed on the Summary tab
- **Number of negative control probes in the panel** (Pre-designed WTA panel: 81 negative control targets, Select panel: 40)
- Number of cells detected: hero metric on the Summary tab

1. The _Negative control probe count_ is calculated as:

   $$ \footnotesize{\text{Q20 decoded transcripts in cells}\times{\text{Adjusted negative control probe rate}}\times{\frac{\text{Number of negative control probes}}{\text{Number of target genes}}}} $$

   where _Q20 decoded transcripts in cells_ is calculated as:

   $$ \footnotesize{\text{Total high quality decoded transcripts}\times{\text{Percent of transcripts within cells}}} $$

2. The `Negative control probe count per control per cell` is then calculated as:

   $$ \footnotesize{{\text{Negative control probe count}}\div{\text{Number of negative control probes}}\div{\text{Number of cells detected}}} $$

3. The `Estimated number of false positive transcripts per cell` is calculated as:

   $$ \footnotesize{{\text{Negative control probe counts per control per cell}}\times{\text{Number of target genes}}} $$

The calculations for "Genomic control probe counts per control per cell" and "Estimated number of false positive transcripts per cell including genomic counts" are analogous to the calculations shown above.

The inputs are:

- Total high quality decoded transcripts
- Percent of transcripts within cells
- **Adjusted genomic control probe rate**
- Number of target genes
- **Number of genomic control probes in the panel** (Pre-designed WTA panel: 61, Select panel: 20)
- Number of cells detected

</LinkableSection>


Negative control metrics

Metric Calculations

Calculating Negative Control Metrics

Atera Instrument Software enables run set up through data egress on the Atera Instrument, including simultaneous on-instrument data analysis by the Atera Onboard Analysis pipeline.

Getting Started

Instrument Software

Analysis

Algorithms

Example Datasets

Release Notes

Advanced

10x Explorer

Analysis Guides

Atera Instrument Software

Storing Atera raw data for reanalysis or grant requirements.

Archiving Atera Data

A quick reference table of Atera Onboard Analysis pipeline output files.

Outputs at a Glance

Overview of Atera Onboard Analysis pipeline output bundle structure and files.

Atera Output Bundle

Overview of interactive Atera HTML summary output files.

Interactive Summaries

Overview of Zarr-formatted cell and transcript output files.

Cells and Transcripts

What is Atera Instrument Software?

View the latest updates to Atera Instrument Software.

Browse Q&As from the 10x Genomics support team.

A collection of introductions, tutorials, and blogs for data analysis beyond 10x Genomics software.