Global and Local Coordinates

Overview

When working with spatial transcriptomics data, it is crucial to understand the difference between local and global coordinate systems:

• Local Coordinates: Coordinates relative to an individual sample/region (0,0 starts at the sample's top-left corner).
• Global Coordinates: Coordinates relative to the entire substrate (flow cell) that contains all samples.

Coordinate System Summary

Data Type	Coordinate System
Registered images (OME-TIFF)	Local (sample-specific)
Cell/nuclei masks (TIFF)	Local (sample-specific)
Transcript data (barcodes.tsv.gz)	Global (substrate-wide)
Cell contour coordinates (CSV)	Global (substrate-wide)

Why Two Coordinate Systems?

The substrate (flow cell) can contain multiple samples, each positioned at different locations. Global coordinates allow all transcripts from all samples to be referenced in a single coordinate space, while local coordinates make it easier to work with individual sample images and masks.

---

1. Transcript Coordinates (Global Space)

Transcript coordinates are always in global substrate coordinate space.

Raw Transcripts/Grid-Binned Data/Cell-Binned Data (barcodes.tsv.gz)

Format: 
sbc:Y:X (in micrometers)
bin10:Y:X (in micrometers)
cell<ID>:Y:X (in micrometers)

Example: cell100003:6441:3653
  - cell100003 = cell ID (matches cell mask files)
  - 6441 = Y-coordinate of cell centroid (µm)
  - 3653 = X-coordinate of cell centroid (µm)

2. Image Coordinates (Local Space)

Registered OME-TIFF files contain multiple image planes in local sample coordinate space:

1. Original-resolution H&E image (1 pixel = variable µm, depends on microscope)
2. 1 µm/pixel H&E image (1 pixel = 1 µm)
3. Tissue mask (1 pixel = 1 µm)

Global Positioning Information

Each sample has a global position on the substrate stored as:

• Global_top: Y-coordinate offset (µm)
• Global_left: X-coordinate offset (µm)

These values define where the sample's local (0,0) is positioned in global substrate space.

---

3. Cell/Nuclei Mask Coordinates

Cell and nuclei mask files come in two formats:

TIFF Masks (Local Space)

• Format: TIFF with pixel intensities = cell IDs
• Resolution: 1 µm/pixel
• Coordinate system: Local to the sample

Contour CSV Files (Global Space)

• *nuclei_contour_coords.csv
• *Expanded_5um_cell_contour_coords.csv
• Format: 3 columns (cell-ID, X-coordinate µm, Y-coordinate µm)
• Coordinate system: Global substrate space

---

How to Extract Global Coordinates

Method 1: From CSV Stats File (Recommended)

The easiest way to get global coordinates is from the stats CSV file.

File location:

intermediate_results/summary/[RunName]_all_stats.csv
or
intermediate_results/stats/sample_prep_stats_sample.csv

The columns of interest are Global_top and Global_left.

Method 2: From OME-TIFF Metadata

Global coordinates are also embedded in the OME-TIFF metadata:

Python code using tifffile:

import tifffile
from ome_types import from_xml

# Read OME-TIFF
ome_tiff_path = "results/15WF_Rep2/15WF_Rep2_registered.ome.tiff"

with tifffile.TiffFile(ome_tiff_path) as tif:
    ome_xml = tif.ome_metadata
    ome = from_xml(ome_xml)
    
    # Get first image metadata
    if ome.images:
        image = ome.images[0]
        if image.pixels and image.pixels.planes:
            # Get position from first plane
            plane = image.pixels.planes[0]
            global_left = plane.position_x  # X-offset (µm)
            global_top = plane.position_y   # Y-offset (µm)
            
            print(f"Sample: {image.name}")
            print(f"Global Top (Y-offset): {global_top} µm")
            print(f"Global Left (X-offset): {global_left} µm")

Installation requirements:

pip install tifffile ome-types