operator.json

{
  "name": "GGRS Plot Operator",
  "description": "High-performance faceted plotting using the GGRS library",
  "tags": ["data visualisation", "export", "reporting", "workflow"],
  "communicationProtocol": "grpc",
  "authors": ["Tercen"],
  "urls": ["https://github.com/tercen/ggrs_plot_operator"],
  "container": "ghcr.io/tercen/ggrs_plot_operator",
  "operatorSpec": {
    "kind": "OperatorSpec",
    "ontologyUri": "https://tercen.com/_ontology/tercen",
    "ontologyVersion": "0.0.1",
    "inputSpecs": [
      {
        "kind": "CrosstabSpec",
        "metaFactors": [
          {
            "kind": "MetaFactor",
            "name": "Page",
            "type": "",
            "description": "These factor(s) will be used to produce one plot file per category.",
            "ontologyMapping": "page",
            "crosstabMapping": "row",
            "cardinality": "0..n",
            "factors": []
          },
          {
            "kind": "MetaFactor",
            "name": "Rows",
            "type": "",
            "description": "Factor(s) to stratify per row.",
            "ontologyMapping": "sample",
            "crosstabMapping": "row",
            "cardinality": "0..n",
            "factors": []
          },
          {
            "kind": "MetaFactor",
            "name": "Columns",
            "type": "",
            "description": "Factor(s) to stratify per column.",
            "ontologyMapping": "variable",
            "crosstabMapping": "column",
            "cardinality": "0..n",
            "factors": []
          }
        ],
        "axis": [
          {
            "kind": "AxisSpec",
            "metaFactors": [
              {
                "kind": "MetaFactor",
                "name": "Y Axis",
                "type": "numeric",
                "description": "Factor to use for the graph's Y axis.",
                "ontologyMapping": "y-axis",
                "crosstabMapping": "y",
                "cardinality": "1",
                "factors": []
              },
              {
                "kind": "MetaFactor",
                "name": "X Axis",
                "type": "",
                "description": "Factor to use for the graph's X axis (optional).",
                "ontologyMapping": "x-axis",
                "crosstabMapping": "x",
                "cardinality": "0..1",
                "factors": []
              },
              {
                "kind": "MetaFactor",
                "name": "Colors",
                "type": "",
                "description": "Factor(s) to use as colors.",
                "ontologyMapping": "variable",
                "crosstabMapping": "color",
                "cardinality": "0..n",
                "factors": []
              },
              {
                "kind": "MetaFactor",
                "name": "Labels",
                "type": "",
                "description": "Factor(s) to use as labels.",
                "ontologyMapping": "variable",
                "crosstabMapping": "label",
                "cardinality": "0..n",
                "factors": []
              }
            ]
          }
        ]
      }
    ],
    "outputSpecs": []
  },
  "properties": [
    {
      "kind": "EnumeratedProperty",
      "name": "theme",
      "defaultValue": "gray",
      "description": "Plot theme matching ggplot2: 'gray' (default with gray background), 'bw' (black and white), 'linedraw' (black lines on white), 'light' (light grey lines), 'dark' (dark background), 'minimal' (no decorations), 'classic' (axis lines, no grid), 'void' (completely empty), 'publish' (clean white background, no grid).",
      "values": ["gray", "bw", "linedraw", "light", "dark", "minimal", "classic", "void", "publish"]
    },
    {
      "kind": "StringProperty",
      "name": "plot.width",
      "defaultValue": "",
      "description": "Plot width in pixels. If left empty or 'auto', dimensions will be derived from the crosstab/facet layout."
    },
    {
      "kind": "StringProperty",
      "name": "plot.height",
      "defaultValue": "",
      "description": "Plot height in pixels. If left empty or 'auto', dimensions will be derived from the crosstab/facet layout."
    },
    {
      "kind": "EnumeratedProperty",
      "name": "backend",
      "defaultValue": "cpu",
      "description": "Render backend: 'cpu' (Cairo) or 'gpu' (OpenGL). GPU is ~10x faster but uses 3x more memory.",
      "values": ["cpu", "gpu"]
    },
    {
      "kind": "EnumeratedProperty",
      "name": "output.format",
      "defaultValue": "png",
      "description": "Output format: 'png' (raster), 'svg' (editable vector), or 'hsvg' (hybrid: vector labels + rasterized data for Inkscape editing).",
      "values": ["png", "svg", "hsvg"]
    },
    {
      "kind": "EnumeratedProperty",
      "name": "legend.position",
      "defaultValue": "right",
      "description": "Legend position: where the legend appears relative to the plot.",
      "values": ["right", "left", "top", "bottom", "inside", "none"]
    },
    {
      "kind": "StringProperty",
      "name": "legend.position.inside",
      "defaultValue": "",
      "description": "Legend coordinates when position='inside'. Format: 'x,y' where x,y ∈ [0,1]. Example: '0.95,0.05' for bottom-right. Only used when legend.position='inside'."
    },
    {
      "kind": "StringProperty",
      "name": "legend.justification",
      "defaultValue": "",
      "description": "Legend anchor point. Format: 'x,y' where x,y ∈ [0,1]. Controls which corner of the legend aligns with the position. (0,0)=bottom-left, (1,1)=top-right, (0.5,0.5)=center. For left/right: y controls vertical alignment. For top/bottom: x controls horizontal alignment."
    },
    {
      "kind": "EnumeratedProperty",
      "name": "png.compression",
      "defaultValue": "fast",
      "description": "PNG compression level: 'fast' (~30% speedup, +15% file size), 'default' (balanced), or 'best' (~40% slower, -10% file size).",
      "values": ["fast", "default", "best"]
    },
    {
      "kind": "StringProperty",
      "name": "plot.title",
      "defaultValue": "",
      "description": "Plot title text. Leave empty for no title."
    },
    {
      "kind": "EnumeratedProperty",
      "name": "plot.title.position",
      "defaultValue": "top",
      "description": "Plot title position: where the title appears relative to the plot.",
      "values": ["top", "bottom", "left", "right"]
    },
    {
      "kind": "StringProperty",
      "name": "plot.title.justification",
      "defaultValue": "0.5,0.5",
      "description": "Plot title justification (anchor point). Format: 'x,y' where x,y ∈ [0,1]. Controls which point of the title aligns with the position. (0,0)=bottom-left, (1,1)=top-right, (0.5,0.5)=center."
    },
    {
      "kind": "StringProperty",
      "name": "axis.x.label",
      "defaultValue": "",
      "description": "X-axis label displayed at the bottom center of the plot. Leave empty for no label."
    },
    {
      "kind": "StringProperty",
      "name": "axis.y.label",
      "defaultValue": "",
      "description": "Y-axis label displayed on the left side of the plot (rotated 270°, reads bottom-to-top). Leave empty for no label."
    },
    {
      "kind": "StringProperty",
      "name": "point.size.multiplier",
      "defaultValue": "1",
      "description": "Multiplier for point/dot size. The crosstab point size (1-10) is multiplied by this value. Use values > 1 for larger dots on big plots, < 1 for smaller dots. Default: 1."
    },
    {
      "kind": "StringProperty",
      "name": "opacity",
      "defaultValue": "1",
      "description": "Opacity for all data elements (points, lines, tiles, bars). Range: 0.0 (transparent) to 1.0 (opaque). Default: 1.0."
    },
    {
      "kind": "StringProperty",
      "name": "axis.x.tick.rotation",
      "defaultValue": "0",
      "description": "X-axis tick label rotation in degrees. Common values: 0 (horizontal), 45 (diagonal), 90 (vertical). Default: 0."
    },
    {
      "kind": "StringProperty",
      "name": "axis.y.tick.rotation",
      "defaultValue": "0",
      "description": "Y-axis tick label rotation in degrees. Common values: 0 (horizontal), 90 (vertical). Default: 0."
    },
    {
      "kind": "BooleanProperty",
      "name": "grid.major.disable",
      "defaultValue": false,
      "description": "Disable major grid lines."
    },
    {
      "kind": "BooleanProperty",
      "name": "grid.minor.disable",
      "defaultValue": false,
      "description": "Disable minor grid lines."
    },
    {
      "kind": "BooleanProperty",
      "name": "axis.lines.disable",
      "defaultValue": false,
      "description": "Disable axis lines, ticks, and panel border."
    },
    {
      "kind": "BooleanProperty",
      "name": "text.disable",
      "defaultValue": false,
      "description": "Disable all text labels (axis titles, tick labels, plot title)."
    },
    {
      "kind": "StringProperty",
      "name": "plot.title.font.size",
      "defaultValue": "",
      "description": "Plot title font size in points. Empty = use theme default (~13.2pt)."
    },
    {
      "kind": "StringProperty",
      "name": "axis.label.font.size",
      "defaultValue": "",
      "description": "Axis label font size in points. Empty = use theme default (~11pt)."
    },
    {
      "kind": "StringProperty",
      "name": "axis.tick.font.size",
      "defaultValue": "",
      "description": "Tick label font size in points. Empty = use theme default (~8.8pt)."
    },
    {
      "kind": "StringProperty",
      "name": "axis.line.width",
      "defaultValue": "",
      "description": "Panel border/axis line width in points. Empty = use theme default (0.5pt)."
    },
    {
      "kind": "StringProperty",
      "name": "filename",
      "defaultValue": "plot",
      "description": "Output filename (without extension). For multi-page plots, page number is appended as a suffix (e.g., 'myplot' becomes 'myplot_p1.png', 'myplot_p2.png'). Default: 'plot'."
    },
    {
      "kind": "EnumeratedProperty",
      "name": "heatmap.cell.aggregation",
      "defaultValue": "last",
      "description": "How to aggregate multiple data points in the same heatmap cell. 'last' matches Tercen's default behavior (last point wins). 'first' uses the first point. 'mean' computes the average. 'median' computes the median.",
      "values": ["last", "first", "mean", "median"]
    },
    {
      "kind": "StringProperty",
      "name": "point.shapes",
      "defaultValue": "19",
      "description": "Point shapes per layer, semicolon-separated (e.g., '19;15;17'). Cycles if fewer shapes than layers. Common shapes: 19=filled circle (default), 15=filled square, 17=filled triangle, 18=filled diamond, 3=plus, 4=cross. Search 'ggplot2 pch' for all 26 shapes (0-25)."
    }
  ]
}