Perspective XY Chart: Aligning Target With Production Bars

Where does the target value travel between the data source and the plot?

The data path has four stages. The binding or script fills props.dataSources with one object per time period. Each entry in props.series points at that source through data.source, data.x (timePeriod), and data.y (a key such as Machine 1 Production). The X axis then turns every distinct timePeriod into a category cell. The render type decides where inside that cell each value is drawn.

The misalignment appears at the last stage. On a category axis, column series are clustered. The chart splits each category cell into one slot per unstacked column series, in the order the series appear in the array. Line and step-line series do not use those slots. Each line point sits at the category location, which is the center of the whole cell, and a step line draws its horizontal segment across the cell. A target plotted as line or stepLine for Machine 1 therefore lands in the middle of the period, not over Machine 1's column. You can hand-tune an offset, but the slot positions move whenever the machine count changes. The machine count changes with the selected time frame and the returned data, so any manual offset breaks as soon as a user picks a different range.

There is also a presentation problem. A line series joins adjacent periods, which tells the reader there is a trend. A per-period target is a reference value for a single bar. It is not a trend, so a marker or bar segment tied to each production column communicates it more accurately.

Check 1: Is this a Perspective XY Chart or a Reporting chart?

Confirm the module before changing anything. The Perspective module and the Reporting module are unrelated. They use different chart components with different configuration models.

Check 2: Does every series find its X and Y on the same row?

Open props.dataSources in the Property Editor and inspect one entry. The working shape is wide format, with one object per period and one key per machine per measure:

{
  "example": [
    {
      "timePeriod": "2025-01",
      "Machine 1 Production": 120,
      "Machine 1 Target": 160,
      "Machine 2 Production": 80,
      "Machine 2 Target": 100
    }
  ]
}

Check 3: How is the target series rendered?

Read the render value on every target series. Each option places the target in a different position relative to the production slot:

The stacked branch works because a stacked column does not claim a new slot. It reuses the slot of the series immediately before it in the array and starts at that series' value. Plot production first and the shortfall (target - production) on top of it. The combined column height equals the target, and the boundary between the two colors marks actual production. Alignment follows the column engine automatically for any number of machines or periods.

If any target is still on line or stepLine, go to Check 4 before rebuilding.

Check 4: Can production exceed target in any period?

The shortfall stack only renders cleanly when the shortfall is zero or positive. When production beats target, target - production goes negative. The stacked segment then draws downward from the top of the production column, which overlaps the production bar and misrepresents both values.

In the three-segment model, the top of base + shortfall always equals the target. When the machine is under target, base is the production value and the shortfall fills the gap. When the machine is over target, base equals the target, shortfall is 0, and the overage segment rises above it in a third color. Total bar height is always the larger of production and target, so neither value is hidden.

How do I build the stacked-shortfall chart?

1. Transform the data. Add a script transform to the binding that feeds props.dataSources.example. The version below handles both branches of Check 4. It keeps the original target and production keys for tooltips and adds the derived keys:

   def transform(self, value, quality, timestamp):
       rows = []
       for rec in value:
           out = {'timePeriod': rec['timePeriod']}
           for key in rec.keys():
               if not key.endswith(' Production'):
                   continue
               machine = key[:-len(' Production')]
               prod = rec[key] or 0
               tgt = rec.get(machine + ' Target', 0) or 0
               out[machine + ' Production'] = prod
               out[machine + ' Target'] = tgt
               out[machine + ' Base'] = min(prod, tgt)
               out[machine + ' Shortfall'] = max(tgt - prod, 0)
               out[machine + ' Overage'] = max(prod - tgt, 0)
           rows.append(out)
       return rows

   If the upstream binding returns a dataset instead of a list of objects, convert it with system.dataset.toPyDataSet and read the columns by name before running this logic. In the two-segment model, plot Production as the base and skip Overage.
2. Order the series array per machine. Stacking is positional, so the order in props.series decides which slot each segment joins. For each machine, emit: base or production (column.appearance.stacked: false), then shortfall (stacked: true), then overage (stacked: true) if used. Every second series in the two-segment model is stacked. Every second and third series in the three-segment model are stacked.
3. Point each series at its key. Keep render: "column" on all of them and change only name, data.y, the stack flag, and the fill:

   {
     "name": "Machine 1 Shortfall",
     "data": { "source": "example", "x": "timePeriod", "y": "Machine 1 Shortfall" },
     "xAxis": "x",
     "yAxis": "y",
     "render": "column",
     "column": {
       "appearance": {
         "fill": { "color": "#FFA500", "opacity": 1 },
         "stroke": { "color": "", "opacity": 1, "width": 0 },
         "stacked": true
       }
     }
   }

   Use one fill color for production and a contrasting color (the orange originally intended for the target) for shortfall on every machine. That keeps the legend readable when the machine count grows.
4. Add a transparent spacer series. With many clustered slots, the groups for adjacent periods run together. Append one extra copy of a production series at the end of the array with stacked: false, fill.opacity: 0, stroke width 0, hiddenInLegend: true, and its tooltip disabled. It claims a blank slot in every category and opens a visible gap between periods.
5. Fix the tooltip semantics. On a stacked series, {valueY} reports the segment value (the shortfall), not the cumulative height. Word the tooltip text as "Shortfall" so operators do not read it as the target.
6. Regenerate the series on time-frame change. Your series builder already runs per selection. Update it so it emits 2 series per machine (or 3 with overage) plus 1 spacer. Derive the machine list from the transformed row keys so that a machine absent from the query does not leave a stacked series pointing at a missing key.

How do I verify the targets are aligned?

1. Load a period with known values. From the sample row, Machine 1 should show a 120 production segment with a 40 shortfall on top, stacking to 160. Machine 2 should show 80 plus 20, stacking to 100.
2. Hover each segment and confirm the tooltip value matches the transformed data in the Property Editor under props.dataSources.example.
3. Switch the selector through weekly, monthly, and yearly. Confirm the stack tops still match the targets when the category count changes and the series array is rebuilt.
4. Force a test row where production exceeds target. Confirm that no segment draws downward, the shortfall is 0, and, in the three-segment model, the overage segment sits above a base equal to the target.
5. Count the column slots in any single category. The count must equal the number of machines plus one blank spacer slot, and each shortfall segment must sit directly on its own machine's production segment.

FAQ