> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# XY Plot Diagram
> Create live XY line plots for engineering data visualization
The XY Plot Diagram is used throughout the modern platform to create live XY line plots. It uses diagram widget type `"xyPlot"`.
## Implementation
```json theme={null}
{
"type": "sheetTemplateWidgets",
"attributes": {
"type": "diagram",
"diagram": [
{
"type": "xyPlot"
}
],
"equation": [
{
"result": "{PARAMETERS}",
"condition": "CONDITIONS"
}
],
"referenceId": "xy_plot_diagram"
}
}
```
## Plot Parameters
| Parameter | Format | Example | Description |
| ----------------- | -------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xData | 1xn Array | `remote.plot.x` | Array of x values against which to plot all yData |
| yData | mxn Matrix | `remote.plot.V` | Matrix of y values to plot. Each row is a new line to plot |
| yEnvelopeData | 2xn Matrix | `remote.plot.VEnv` | (optional) Matrix in which one row is the minimum and the other row is the maximum in an envelope. Space between the lines will be filled with a light grey |
| yLabels | 1xn array of strings | `remote.plot.lc` | (optional) Labels for each line / row in yData |
| yColors | 1xn array of strings | `["#3DB318"]` | (optional) Colours, in hex format, to use for each line / row in yData |
| yAxisLabel | string | `"Shear (kN)"` | (optional) String with which to label the y axis |
| xAxisLabel | string | `"Distance from Left (mm)"` | (optional) String with which to label the x axis. No label will display if this parameter is excluded |
| height | integer | `200` | (optional: defaults to 200) Height, in pixels, of the plot |
| column | boolean | `true` | (optional; defaults to `false`) Rotates the plot 90 degrees and arranges legends and axes to fit appropriately, generally used for plotting column data |
| minScale | float | `0.01` | (optional; defaults to 0.01) Sets a minimum absolute scale to plot, so that plots don't give ugly `NaN` values or start zooming in so much that they start showing floating point precision |
| xScale | string | `"log"` | (optional; defaults to `"linear"`) Options are `"linear"`, `"log"`, `"sqrt"`, and `"time"`. See [Victory Documentation](https://formidable.com/open-source/victory/docs/common-props/#scale) |
| yScale | string | `"log"` | (optional; defaults to `"linear"`) Same as `xScale`, but for the Y-axis |
| xAxisValues | array | `[1, 10, 100, 1000, 10000]` | (optional; defaults to `[]`, which means automatic) If Victory seems to be coming up with weird axis values, you can manually set it here |
| yAxisValues | array | `[1, 10, 100, 1000, 10000]` | (optional; defaults to `[]`, which means automatic) If Victory seems to be coming up with weird axis values, you can manually set it here |
| customLines | dict | `xsect.lines` | Format: `[{"points": [[x0, y0], [x1, y1], ...], "color": "#000", "lineWeight": 3, "name": "Global"},{"points":...}]` |
| legendItemsPerRow | integer | `5` | Format: Number of items to show per row of the legend |
## Basic Data Format
### Single Line Plot
```javascript theme={null}
{
xData: [0, 1, 2, 3, 4, 5],
yData: [[0, 10, 15, 12, 8, 0]], // Note: yData is always a matrix
yLabels: ["Shear Force"],
yColors: ["#3DB318"],
xAxisLabel: "Distance (m)",
yAxisLabel: "Shear (kN)"
}
```
### Multiple Line Plot
```javascript theme={null}
{
xData: [0, 1, 2, 3, 4, 5],
yData: [
[0, 10, 15, 12, 8, 0], // First line
[0, -5, -8, -6, -3, 0], // Second line
[5, 8, 12, 10, 6, 2] // Third line
],
yLabels: ["Dead Load", "Live Load", "Wind Load"],
yColors: ["#3DB318", "#FF3520", "#1E88E5"],
xAxisLabel: "Distance (m)",
yAxisLabel: "Moment (kNm)"
}
```
## Envelope Plots
Envelope plots show a range of values with shaded areas:
```javascript theme={null}
{
xData: [0, 1, 2, 3, 4, 5],
yData: [[5, 8, 12, 10, 6, 2]], // Main line
yEnvelopeData: [
[3, 6, 9, 7, 4, 1], // Minimum values
[7, 10, 15, 13, 8, 3] // Maximum values
],
yLabels: ["Design Value"],
yColors: ["#3DB318"],
xAxisLabel: "Distance (m)",
yAxisLabel: "Moment (kNm)"
}
```
## Custom Lines
Add custom reference lines or annotations:
```javascript theme={null}
{
// ... regular plot data
customLines: [
{
points: [[0, 100], [5, 100]], // Horizontal line at y=100
color: "#FF0000",
lineWeight: 2,
name: "Capacity"
},
{
points: [[2.5, 0], [2.5, 120]], // Vertical line at x=2.5
color: "#FFA500",
lineWeight: 3,
name: "Critical Section"
}
]
}
```
## Scale Options
### Logarithmic Scales
```javascript theme={null}
{
xData: [1, 10, 100, 1000, 10000],
yData: [[0.1, 1, 10, 100, 1000]],
xScale: "log",
yScale: "log",
xAxisValues: [1, 10, 100, 1000, 10000], // Manual axis values
yAxisValues: [0.1, 1, 10, 100, 1000]
}
```
### Square Root Scale
```javascript theme={null}
{
xData: [0, 1, 4, 9, 16, 25],
yData: [[0, 10, 20, 30, 40, 50]],
xScale: "sqrt",
xAxisLabel: "Square of Distance"
}
```
## Column Mode
For vertical data presentation:
```javascript theme={null}
{
xData: [0, 1, 2, 3, 4], // Height levels
yData: [[100, 80, 60, 40, 20]], // Load values
column: true,
xAxisLabel: "Height (m)",
yAxisLabel: "Load (kN)",
height: 300
}
```
## Complete Example
```json theme={null}
{
"type": "sheetTemplateWidgets",
"attributes": {
"type": "diagram",
"diagram": [
{
"type": "xyPlot"
}
],
"equation": [
{
"result": "{
xData: remote.plot.x,
yData: [remote.plot.M, remote.plot.V],
yEnvelopeData: remote.plot.MEnvelope,
yLabels: [\"Moment\", \"Shear\"],
yColors: [\"#3DB318\", \"#FF3520\"],
xAxisLabel: \"Distance (m)\",
yAxisLabel: \"Force/Moment\",
height: 250,
customLines: [
{
points: [[0, capacity], [beam_length, capacity]],
color: \"#FF0000\",
lineWeight: 2,
name: \"Capacity\"
}
],
legendItemsPerRow: 3
}",
"condition": "@default"
}
],
"referenceId": "moment_shear_diagram",
"label": "Moment and Shear Diagram",
"showInSuperSummary": true
}
}
```
## Best Practices
1. **Data Structure**: Always format `yData` as a matrix, even for single lines
2. **Colors**: Use consistent color schemes across related diagrams
3. **Labels**: Provide clear axis labels and units
4. **Scale Selection**: Choose appropriate scales for your data range
5. **Performance**: Use `minScale` to avoid precision issues with very small values
The XY Plot uses the Victory.js charting library. For advanced scaling options, refer to the [Victory Documentation](https://formidable.com/open-source/victory/docs/common-props/#scale).
Use envelope plots to show uncertainty ranges or to highlight the difference between maximum and minimum values in load combinations.
When using logarithmic scales, ensure that all data points are positive. Zero or negative values will cause rendering issues.
## Integration with Solvers
XY plots work excellently with beam and frame solver results:
```json theme={null}
{
"type": "sheetTemplateWidgets",
"attributes": {
"type": "remote",
"solver": "beam",
"equation": [
{
"condition": "@default",
"result": "{
// ... beam parameters
plotMoment: true,
plotShear: true,
plotDeflection: true
}"
}
],
"referenceId": "beam_results"
}
}
```
The solver automatically provides formatted plot data that can be directly used in XY plot diagrams.