Standard p-column annotations
This document lists standard annotations used in block development for p-column specifications. These annotations provide hints for the UI, define behavior in workflows, and add semantic meaning to the data. They are applied to the annotations field of either a PColumnSpec or an AxisSpec.
Technical annotations
| Name | Applies to | Description | Values |
|---|---|---|---|
pl7.app/label | both | A human-readable label for UI display. | Any string |
pl7.app/description | both | Biological description of column content | Any string |
pl7.app/isAnchor | values | Flags a p-column as the anchor for a dataset. | "true", "false" |
pl7.app/axisNature | axis | Describes how axis values are compatible. | homogeneous, scaleCompatible, heterogeneous |
pl7.app/axisKeys/$idx | axis | Provides a predefined list of all values for an axis. | JSON-encoded array of strings |
pl7.app/trace | values | Records the processing history of the p-column. | JSON-encoded Trace object |
pl7.app/axisNature
This annotation defines the semantic and visual compatibility of data points along an axis.
homogeneous: Indicates that indices along this axis represent the same kind of data, allowing for direct comparison and joint visualization.scaleCompatible: Indicates that values can be plotted on the same visual scale but are semantically different. Data points should be visually distinguished (e.g., by color or grouping).heterogeneous: Signifies that indices represent fundamentally different data types or units (e.g., mass vs. time), often called "apples and oranges".
Table annotations
These annotations control the appearance and behavior of p-columns and axes within tabular views like PlAgDataTableV2.
| Name | Applies to | Description | Values |
|---|---|---|---|
pl7.app/table/visibility | both | Controls the default visibility of a column or axis in a table. | default, optional, hidden |
pl7.app/table/orderPriority | both | Sets the display order priority for a column or axis in a table. | Any integer (represented as a string) |
pl7.app/table/longText | values | Renders a cell with a viewer optimized for long text content. | true, false |
pl7.app/format | both | Specifies a number format using d3-format notation. | A valid d3-format string |
pl7.app/table/fontFamily | both | Specifies the font family for text in the table. | e.g., monospace |
pl7.app/table/visibility
Controls whether a column is visible by default.
default: The column is visible by default.optional: The column is hidden by default but can be shown by the user.hidden: The column is hidden and cannot be made visible by the user.
pl7.app/table/orderPriority
This annotation determines the initial order of columns and axes in a table.
- Higher values have higher priority and appear further to the left. For example, a column with
"pl7.app/table/orderPriority": "100"will appear before a column with"pl7.app/table/orderPriority": "10". - Absence of the annotation is treated as the lowest possible priority, moving the column to the far right.
- Note: Annotation values are always strings and must be parsed as integers for comparison.
- The "MiXCR Clonotyping" block produces columns with this annotation and can be used as a reference.
Filters in tables & graphs
These annotations are used to configure filtering controls in the UI.
| Name | Applies to | Description | Values |
|---|---|---|---|
pl7.app/isDiscreteFilter | both | Indicates that the column data can be used for discrete filtering (e.g., a dropdown with checkboxes). | true, false |
pl7.app/discreteValues | both | Provides a list of predefined values for a discrete filter. | JSON-encoded array of strings |
pl7.app/min | both | Specifies the minimum value for a continuous (range) filter. | number |
pl7.app/max | both | Specifies the maximum value for a continuous (range) filter. | number |
pl7.app/isSubset | both | Column can be used for filtering only as subset ('is not NA') filter. | true, false |
Data visualization annotations
These annotations are used to configure plots settings in graph-maker.
| Name | Applies to | Description | Values |
|---|---|---|---|
pl7.app/graph/thresholds | both | Contains data about significant lines on plot. Works for scatterplot, if column with the annotation is in Grouping. Used, for example, in Volcano plot. | JSON-encoded array of structure: {columnId: {valueType: ValueType, name: string}, value: number} |
pl7.app/graph/axis/lowerLimit | both | Provides lower limit for plot's viewport along an X/Y axis. | number |
pl7.app/graph/axis/upperLimit | both | Provides lower limit for plot's viewport along an X/Y axis. | number |
pl7.app/graph/axis/symmetricRange | both | Provides central value for plot's viewport along an X/Y axis. | number |
pl7.app/graph/palette | both | Set color mapping that can't be changed in the interface. Used for Volcano plot. | JSON-encoded structure: {mapping: Record<string, number>, name: string}, where 'mapping' is mapping of column values to palette color indexes, 'name' is palette name ('salinity', 'magma' etc.) |
pl7.app/graph/axis/highCardinality | axis | If data-input (X,Y,Data value etc.) has column with axis with this annotation plot can't be rendered until this axis or another column with this axis is moved to the Filters. | true,false |
pl7.app/graph/isVirtual | values | Marker for the columns that created in createPFrameForGraphs with additional domain values for compatibility in plot's data-mapping. | true, false |
pl7.app/graph/isDenseAxis | axis | For a column with these axes there will be added artificial column to join request. This needed to get all the combinations of 'dense' axes values in join result, even if they do not exist in pframe. | true, false |
pl7.app/graph/treatAbsentValuesAs | values | Fill this values instead of null for absent items in join response for plot. | number |
Score and ranking annotations
These annotations are used to flag p-columns that represent a score or a metric that can be used for ranking and selection of "top" clonotypes. This allows downstream blocks, like a "Top Antibodies" or "Lead Candidates" block, to automatically discover and use these columns for sorting and filtering.
| Name | Applies to | Description | Values |
|---|---|---|---|
pl7.app/isScore | values | (Required) Flags a p-column as containing score values that can be ranked. | true, false |
pl7.app/score/rankingOrder | values | (Required) Describes the natural ranking order of the scores. For example, a lower distance-to-centroid is "better", while a higher mutation count might be "better". | increasing, decreasing |
pl7.app/score/defaultCutoff | values | Defines a default cutoff value for the scores. This is a hint for UI components to pre-select a sensible filtering threshold. | A number or a JSON-encoded array of strings |