Skip to main content

Label p-columns

In the Platforma ecosystem, we distinguish between stable, machine-readable identifiers and mutable, human-readable labels. For example, a sample has a unique, permanent sampleId, but a user might want to refer to it with a descriptive name like "Day 7 Post-Infusion". If this descriptive name were used as the primary key, changing it would trigger massive recalculations.

To solve this, we use label p-columns.

The pl7.app/label p-column​

A label p-column is a special p-column with the reserved name pl7.app/label. Its purpose is to store the human-readable labels for the keys of another axis.

The key features of a label p-column are:

  • Name: Its name is always pl7.app/label. This is the sole identifier for a label column.
  • Axis: It is keyed by the axis it provides labels for (e.g., pl7.app/sampleId or pl7.app/vdj/clonotypeKey).
  • Value Type: The valueType is always String.

Example 1: Sample labels​

A pl7.app/label column for samples provides a human-readable Sample Name for each unique sampleId.

# The label p-column spec
name: pl7.app/label
valueType: String
axesSpec:
  - name: pl7.app/sampleId
    type: String
    # ... other axis properties
annotations:
  # This provides a display name for the label column itself.
  "pl7.app/label": "Sample Name"

Example 2: Clonotype labels​

A pl7.app/label column for VDJ clonotypes provides a short, human-readable label for a long, complex clonotypeKey.

# The label p-column spec
name: pl7.app/label
valueType: String
axesSpec:
  - name: pl7.app/vdj/clonotypeKey
    type: String
    # ... other axis properties
annotations:
  "pl7.app/label": "Clonotype Label"

Downstream tools and UI components can query for the pl7.app/label column that is keyed by the axis of interest (e.g., clonotypeKey) to display meaningful names to the user instead of raw identifiers.