The cellspec 1.0 format

1. Object

A cellspec object is a list of class "cellspec" with these components:

A whole slide carries up to about 1,000 numeric features for millions of cells. A double matrix stores them compactly and maps directly to an assay of a SpatialExperiment; cells stays a data frame because it holds mixed types. Accessors return plain data frames. Rows of measurements are aligned with cells by position; row names are not used.

x <- cs_example()
x
#> <cellspec> spec 1.0.0
#>   cells     80 in 2 images (2 samples)
#>   features  19: 16 intensity, 2 shape, 1 other
#>   markers   4: DAPI, CD3e, Pan-Cytokeratin, FOXP3
#>   pixel     0.5 um/px
#>   adjacency none
#>   source    simulate 1.0.0 (cellspecR simulator 1.1.0)

2. Cells

Rules:

• The key (image_id, cell_id) MUST be unique.
• x and y MUST be finite. area, when present, MUST be positive or NA.
• Identifiers are character columns, never row names.
• Additional columns are allowed and SHOULD be snake_case. The prefixes region__ and boundary_distance__ are reserved for region annotations and cs__ for internal use. A layer name MUST match ^[A-Za-z0-9][A-Za-z0-9_.-]*$.
• cells MUST NOT contain clinical variables; subject_id belongs in images.

3. Measurements

• A double matrix with one row per cell.
• Column names are feature identifiers and MUST equal dictionary$feature_id, in the same order.
• Values are kept as exported by the source tool, in raw units. No transformation is applied on import. NaN and infinite values from sources are converted to NA and counted in provenance$counts.

4. Dictionary

Controlled vocabularies:

• kind: intensity, shape, other.
• compartment: cell, nucleus, cytoplasm, membrane, or NA for other features.
• statistic for intensity features: mean, median, sd, min, max, sum, variance.
• statistic for shape features: area, perimeter, length, circularity, solidity, max_diameter, min_diameter, max_caliper, min_caliper, eccentricity, major_axis_length, minor_axis_length, extent, orientation, nucleus_cell_area_ratio. Unknown shape measurements are stored as kind = "other", never dropped.
• unit: a.u., um, um2, px, px2, rad, 1.

Feature identifiers are generated by readers and follow one rule per kind:

Downstream code MUST select features through their dictionary columns, for example with cs_features(), and not by splitting identifiers. Marker names MUST be trimmed and MUST NOT contain :. Because identifiers follow the rule above and are unique, no two features can describe the same kind, marker, compartment and statistic.

cs_features(x, kind = "intensity", marker = "FOXP3")
#> [1] "cell:FOXP3:mean"      "cell:FOXP3:median"    "nucleus:FOXP3:mean"  
#> [4] "nucleus:FOXP3:median"

5. Images and channels

Every intensity marker in the dictionary MUST appear in channels$marker for every image of the object. A channel without measurements is allowed, for example a nuclear stain used only for segmentation.

6. Provenance

provenance is a list with at least these fields:

Input paths are stored as file names plus hash. Full paths leak private directory structures and are stored only when a user explicitly asks for it.

7. Adjacency (optional)

method is one of mask_touching, polygon_intersection, delaunay. Each unordered pair of cells appears at most once, ordered so that cell_id_a sorts before cell_id_b in byte order, and both cells MUST exist in cells. Subsetting an object drops contacts whose cells were removed.

8. Coordinate frame and units

• The origin is the top-left corner of the top-left full-resolution pixel; x increases to the right and y increases downward (the QuPath convention).
• The centre of the pixel with 0-based index i lies at (i + 0.5) * pixel_size.
• Centroids x and y are in micrometres. Readers that receive pixel centroids MUST know the pixel size, from the file or from an argument, and MUST stop otherwise.
• When a tool reports both micrometre and pixel centroids, readers check that abs(x - x_px * pixel_size) <= 0.5 * pixel_size and stop on disagreement.
• The micro sign appears in exports as U+00B5, U+03BC, um or the mis-decoded µ. Readers normalise these variants before matching headers and keep the original header in source_name.

9. Directory layout

A cellspec directory holds one object on disk:

<dir>/
  cells.parquet       cells columns, then one column per feature_id
  cellspec.json       spec_version, column types, dictionary, images,
                      channels, provenance
  adjacency.parquet   optional
  MANIFEST.sha256     "<sha256>  <relative path>" for every file above
  DONE                written last; holds the SHA-256 of MANIFEST.sha256

• The cell table is stored as Parquet by default, which keeps every double bit-exact. A tab-separated alternative (cells.tsv.gz, adjacency.tsv.gz) is readable by any tool; its numbers carry 15 significant digits, so values can differ from the originals in the last representable digits.
• cellspec.json validates against the JSON Schema shipped in system.file("schema", "cellspec-1.0.0.schema.json", package = "cellspecR").
• Writers stage the directory under a temporary name and rename it at the end, so a directory without DONE was not completely written.
• Readers refuse a directory without DONE, with a manifest mismatch, or with an unsupported major spec_version.

10. Validation rules

cs_validate() checks an object against the rules above. Structure checks implement the MUST rules and fail; semantic checks flag implausible content and warn.

11. Versioning

• spec_version follows semantic versioning. Minor versions only add optional columns or components.
• A reader of major version 1 accepts every 1.y object whose minor version is not newer than its own.
• Readers of tool exports carry their own adapter_version, which changes whenever their output for the same input changes.