Dataset Format#

A dataset combines modality-specific images with shared tissue identifiers, segmentation masks, and tile coordinates. OME-Zarr stores image arrays; Parquet stores tables; compressed NumPy files store masks.

Directory Layout#

my_dataset
- metadata
  - tissues.parquet
  - cells.parquetif cell segmentations exist
- he
  - 1_0mpp
    - images
      - <tissue_id>.ome.zarr
- imcor codex, cycif, mibi
  - channels.parquet
  - channels_per_tissue.parquet
  - 1_0mpp
    - images
      - <tissue_id>.ome.zarr
    - standardization
      - quantile_clippingmethod
        uq_0.99_imageclipping quantile and level
- ihc
  - ihc_<marker>
    - 1_0mpp
      - images
        <tissue_id>.ome.zarr
- segmentations
  - 1_0mpp
    - tissue_masks
      - <tissue_id>.npz
    - cell_masks
      - instancesoptional
        <tissue_id>.npz
      - <task>optional, e.g. cell types
        <tissue_id>.npz
        label_encoder.parquet
- tiling
  - 1_0mpp
    - defaulttiling strategy
      - 224_tile_coordinates.parquet
      - 224_tile_stats.parquet

Only include modalities that exist. Modality-specific images and channel tables live in one directory per modality; segmentations and tiling are shared by all modalities.

Resolutions are given in micrometres per pixel (mpp) and encoded as directory names with an underscore in place of the decimal point: resolution=1.0 resolves to 1_0mpp, 0.5 to 0_5mpp, and 0.65 to 0_65mpp. Pass a float or the string directly. These directories hold images already sampled at that pixel spacing; choosing a resolution in a constructor does not resample the data.

Naming Conventions#

Use lowercase for all names, such as dataset, modality, and directory names, and join words with underscores. Gene and marker names are the only exception. They follow the official HUGO nomenclature.

If possible, name the dataset directory after the Google Scholar BibTeX key of the publication that introduced the data, in the form <lastname><year><firsttitleword> without separators. For example, Schürch et al. (2020) becomes schurch2020coordinated.

Tissue Metadata#

Write one row per tissue–modality pair to metadata/tissues.parquet. The same tissue ID may occur in multiple modalities. Use string identifiers consistently.

Required columns#
Column	Requirement
`dataset`	Name of the dataset, identical to the dataset directory name.
`tissue_id`	Unique tissue identifier of the form `<dataset>_<patient_id>_<specimen_id>` (see Tissue IDs). Must match image and mask filenames, without extensions.
`patient_id`	Pseudonymous patient identifier: an 8-character lowercase hash of the patient identifier in the source data. Compute it with `hash_patient` from the dataset creation utilities.
`specimen_id`	Four-digit specimen index per patient. `0000` if the patient has a single tissue, otherwise an incrementing index from `0000` to `n`.
`modality`	`he`, `imc`, `codex`, `cycif`, `mibi`, or `ihc_<marker>`. The marker name of IHC modalities follows HUGO, for example `ihc_CD3E`. If the marker name is a word, only its first letter is uppercase, for example `ihc_E-Cadherin`.
`alignment`	`"exact"` if the image is spatially registered with the images of the same tissue in other modalities, otherwise `"no alignment"`. Use `np.nan` for every row of a unimodal dataset.

Recommended metadata#
Column	Description
`split`	Data split, such as `train` or `test`. Labels are user-defined. Required when a constructor receives `split`.
`original_file_name`	The original file name of the image, to trace each tissue back to its source.
`original_patient_identifier`	The patient identifier of the original dataset, to trace each hash back to its source.
Clinical metadata	Any clinical variables available for the patient or tissue.

Tissue IDs#

A tissue ID combines the dataset name, the patient hash, and the specimen index: <dataset>_<patient_id>_<specimen_id>, for example schurch2020coordinated_abcdefgh_0000.

Images of different modalities share a tissue ID only if they show the same physical tissue, have the same size, and are spatially registered. Images of the same tissue that are not registered receive different specimen IDs. Because masks and tile coordinates are stored per tissue ID, this rule guarantees that they apply to every modality of the tissue.

Note

Keep tissue_id as a regular column when saving. The current base loader calls set_index("tissue_id").

Cell Metadata#

Provide metadata/cells.parquet whenever cell segmentations are available. Each row describes one cell. The table requires two regular columns, not a DataFrame index:

tissue_id: the tissue the cell belongs to.
cell_id: an integer that equals the cell’s label in the instance mask segmentations/<resolution>/cell_masks/instances/<tissue_id>.npz.

Further columns, such as cell-type annotations or mean marker intensities, are optional.

Image Arrays#

Store every image as an OME-Zarr 0.5 store on Zarr v3, named <tissue_id>.ome.zarr. The store contains a single array at path 0 with (C, H, W) axis order and the dimension names c, y, and x. The omero metadata of the store lists the channel labels.

Write the array in chunks of 256×256 pixels that span all channels, so that every read of a region loads all of its channels at once. The shard size depends on the dataset. Choose it so that an image has at most 100 shards.

The loaders read array 0 directly. They do not infer axes from OME metadata or select an arbitrary pyramid level. Remove or explicitly select time and depth dimensions before writing a two-dimensional tissue image. Images can be written directly in this format. Alternatively, write plain <tissue_id>.zarr arrays and convert them with scripts.convert_dataset_to_omezarr (see Convert New Datasets). Plain .zarr stores are not read by the loaders.

H&E and marker-specific IHC use three RGB channels. For H&E, built-in preprocessing divides intensities by 255 before mean/std normalization, so retain the corresponding 0–255 scale. Multiplex arrays contain only the channels measured for that tissue, in cohort channel-table order. Preserve measurement values and record all resampling or intensity transformations.

Channel Metadata#

<modality>/channels.parquet defines the ordered cohort panel. channels_per_tissue.parquet is a boolean availability matrix with tissue IDs as its index and channel names as its columns, in the same order as the panel indicated by channels.parquet.

Channel table fields#
Field	Meaning
`channel_name`	Required. Channel name; use unique names matching availability-table columns.
`qc_pass`	Required. Boolean quality-control flag. Set it to `False` if the channel does not pass quality control, which flags it as unusable.
`uniprot_id`	Required. UniProt identifier of the marker, used for UniProt filtering. Enter `pd.NA` if no UniProt ID is available, for instance for non-protein markers.
`is_nuclear_marker`	Required. Boolean flag that marks nuclear markers, used by optional nuclear-marker ID replacement.
`description`	Optional. Free-text notes on the channel.

For example, if the cohort panel is [A, B, C] and a tissue has availability [True, False, True], its image must store two channels in order [A, C]. Do not write a zero-filled channel B and mark it absent. Missing availability files fall back to all channels present; explicitly write the matrix for reproducibility.

The loaders use these tables to filter channels in three levels, selected with kind: complete keeps all channels measured for the tissue, qc_filtered those that pass quality control (qc_pass), and uniprot_filtered those that also have a valid UniProt ID, for aligned protein-centric analysis.

Masks and Spatial Alignment#

Tissue masks use np.savez_compressed(path, mask=mask) with a boolean (H, W) array. Cell instance masks use integer labels and the same key: 0 marks the background, and the labels 1 to N identify the individual cells. Cell task masks, such as cell-type maps, store integer class IDs. Not every cell has to be assigned a class, so a task mask may label fewer cells than the instance mask. the label_encoder.parquet next to them maps each ID to a label with a name column and an id column (an index column is accepted instead of id). The spatial shape must match the corresponding images at that resolution.

Masks and tiling are shared by tissue ID. Images of different modalities share a tissue ID only if they show the same physical tissue, have the same size, and are spatially registered (see Tissue IDs). The package does not validate or compute that registration.

Tile Coordinates#

Tile-coordinate Parquet files contain tissue_id, tile_id, row, and col. Coordinates describe the top-left pixel in the stored-resolution image. row is the vertical coordinate; col is horizontal. Use the supplied script to generate the companion tile-statistics file.

The default strategy expects in-bounds tiles. Store padded grid tiles under a separate strategy such as grid_stride224 and pass it as tile_strategy.

scripts.compute_tiling computes the coordinates from the tissue masks. The default algorithm, best_mask_tiling_try_to_stop, greedily adds the tile that covers the most new tissue and stops once two criteria are both met: coverage has reached coverage_goal, and the best remaining tile adds fewer than min_gain_ratio new pixels. The fixed-grid alternative, get_grid_tile, pads the mask extent with background and keeps windows whose tissue fraction is at least 1 - tolerance; edge windows keep their top-left coordinates even when they extend past the image, and the loaders zero-pad them.

Standardization Statistics#

A standardization value such as quantile_clipping/uq_0.99_image maps to the same relative directory below <modality>/<resolution>/standardization/. The suffix records the clipping-quantile level. Mean and standard deviation files describe values after the chosen clipping transform. Standardization explains how to generate and use them; do not mix statistics from different standardization values.

Minimum versus Derived Files#

Basic image loading needs tissue metadata and image stores; multiplex loading also needs a channel table and should include explicit availability. Tissue masks are needed for mask-based tiling. Tile files are needed for indexed tile sampling. Statistics are needed only for the selected statistics-backed preprocessing.