Graph

The view elements on this page additionally accept the attributes common to all view elements.

The graph element will show a plot of the YBUFFER data against the XBUFFER data. The input buffers are defined by input tags within the value block and need to be data-containers (see above). The input tags are linked to the axes with an additional axis attribute to the input tag, which may be x or y. See below for additional options for other graph types.

The attribute partialUpdate is used for performance optimization. PartialUpdate should be set to true when the buffer is never changed entirely, but new data is just appended with increasing x values. PartialUpdate then allows only this new data to be transferred to the web interface to save bandwidth.

<graph labelX="STRING" labelY="STRING" labelZ="STRING" unitX="STRING"
       unitY="STRING" unitZ="STRING" unitYperX="STRING" timeOnX="BOOLEAN"
       timeOnY="BOOLEAN" systemTime="BOOLEAN" linearTime="BOOLEAN"
       hideTimeMarkers="BOOLEAN" aspectRatio="FLOAT" style="STRING"
       partialUpdate="BOOLEAN" history="INTEGER" lineWidth="FLOAT"
       color="COLOR" logX="BOOLEAN" logY="BOOLEAN" logZ="BOOLEAN"
       xPrecision="INTEGER" yPrecision="INTEGER" zPrecision="INTEGER"
       suppressScientificNotation="BOOLEAN" scaleMinX="STRING"
       scaleMaxX="STRING" scaleMinY="STRING" scaleMaxY="STRING"
       scaleMinZ="STRING" scaleMaxZ="STRING" minX="FLOAT" maxX="FLOAT"
       minY="FLOAT" maxY="FLOAT" minZ="FLOAT" maxZ="FLOAT" followX="BOOLEAN"
       mapWidth="INTEGER" showColorScale="BOOLEAN" mapColor[N]="COLOR"
       interpolateMapColors="BOOLEAN" pickLabel="STRING">
    <input axis="STRING" color="COLOR" lineWidth="FLOAT" style="STRING">TEXT</input>
    <output axis="STRING" label="STRING">TEXT</output>
</graph>

Attributes

labelX

The label of the x axis

added in 1.7 optional, translatable

labelY

The label of the y axis

added in 1.7 optional, translatable

labelZ

The label of the z axis

optional, translatable

unitX

The unit of the x axis

added in 1.7 optional, translatable

unitY

The unit of the y axis

added in 1.7 optional, translatable

unitZ

Unit of the z axis.

optional, translatable

unitYperX

An explicit unit for slopes. If not set, phyphox will use "unitY / unitX".

added in 1.10 optional, translatable

timeOnX

If set to true, the x data needs to be time data in seconds relative to the first start of the experiment. This allows marking start/pause events and switching to a system time scale (i.e. absolute date and time) on the x axis.

added in 1.12 optional, boolean, default: false

timeOnY

If set to true, the y data needs to be time data in seconds relative to the first start of the experiment. This allows marking start/pause events and switching to a system time scale (i.e. absolute date and time) on the y axis.

added in 1.12 optional, boolean, default: false

systemTime

If set to true, time axes will start as a system time scale (they can always be switched by the user).

added in 1.12 optional, boolean, default: false

linearTime

If set to true, the time on each axis is interpreted as "linear" time, which is identical to "experiment" time with the difference that the time stamp increases even when phyphox is paused. This especially allows plotting data from external sources that have their own internal clock. In these cases you can use the timer module to get a reference time to shift data from an external clock appropriately. If the graph is shown with system time on the axis, all data is shown, but if the axis is set to experiment time, the data points with linear time corresponding to times during which phyphox was paused will be hidden. If linearTime is set to false, experiment time (the default) is expected.

added in 1.12 optional, boolean, default: false

hideTimeMarkers

If set to true, no red markers are shown to indicate times at which the experiment was stopped.

added in 1.14 optional, boolean, default: false

aspectRatio

The ratio of the total width of this element to its total height in the view, including labels and axes.

optional, float, default: 2.5

style

If set to dots, the graph will not connect the values with lines. See below for additional styles introduced with file format 1.7 (phyphox 1.1.0).

added in 1.7 optional, one of lines, dots, hbars, vbars, map, default: lines

partialUpdate

If set to true, this allows optimizations which only work if the data is appended with increasing x values. A typical example is sensor data: Only few new values are added and each data point has a greater timestamp than the previous one. In such cases this should be set to true as it allows the web interface to only transfer these new datapoints.

optional, boolean, default: false

history

Deprecation warning: This feature has been marked as deprecated and will be removed soon. Please implement it in phyphox analysis logic by using additional data-containers and copying the shown graph into these on each update. This has several advantages like being able to export the history data and better control over its style. Original description: The number of graphs to be shown. 1 means, that the current data is shown. n means, that n graphs are shown, with n-1 graphs containing the data from the previous update. This attribute only makes sense, when the whole graph is replaced on each analysis cycle and can be used to compare the previous n results within a single graph. Deprecated since phyphox file format 1.15 (phyphox 1.1.12))

added in 1.15 optional, integer, default: 1

lineWidth

Width of the graph line relative to the default width

optional, float, default: 1.0

color

Color of the graph line as six-digit RGB hex value or a named choice from the phyphox Colors

optional, color

logX

If set to true, the x axis will be on a logarithmic scale

optional, boolean, default: false

logY

If set to true, the y axis will be on a logarithmic scale

optional, boolean, default: false

logZ

If set to true, the z axis will be on a logarithmic scale

optional, boolean, default: false

xPrecision

The number of significant digits on the x axis.

added in 1.2 optional, integer, default: -1

yPrecision

The number of significant digits on the y axis.

added in 1.2 optional, integer, default: -1

zPrecision

The number of significant digits on the z axis.

optional, integer, default: -1

suppressScientificNotation

If set to true, phyphox will never use scientific notation like 2e-5 instead of 0.00002. This also changes the behavior of xPrecision and yPrecision to refer to decimal digits instead of significant digits. Please make sure that this works well with your measured data as forcing non-scientific notation can lead to extreme numbers in some edge cases.

added in 1.19 optional, boolean, default: false

scaleMinX

Method to scale the minimum of the x axis. auto always scales this value to the minimum of the data set. extend scales to the historic minimum. fixed sets the minimum to minX.

optional, one of auto, extend, fixed, default: auto

scaleMaxX

Method to scale the maximum of the x axis. auto always scales this value to the maximum of the data set. extend scales to the historic maximum. fixed sets the maximum to maxX.

optional, one of auto, extend, fixed, default: auto

scaleMinY

Method to scale the minimum of the y axis. auto always scales this value to the minimum of the data set. extend scales to the historic minimum. fixed sets the minimum to minY.

optional, one of auto, extend, fixed, default: auto

scaleMaxY

Method to scale the maximum of the y axis. auto always scales this value to the maximum of the data set. extend scales to the historic maximum. fixed sets the maximum to maxY.

optional, one of auto, extend, fixed, default: auto

scaleMinZ

Method to scale the minimum of the z axis. auto always scales this value to the minimum of the data set. extend scales to the historic minimum. fixed sets the minimum to minZ.

optional, one of auto, extend, fixed, default: auto

scaleMaxZ

Method to scale the maximum of the z axis. auto always scales this value to the maximum of the data set. extend scales to the historic maximum. fixed sets the maximum to maxZ.

optional, one of auto, extend, fixed, default: auto

minX

Lowest value on the x axis. Only applied if scaleMinX = fixed

optional, float, default: 0.0

maxX

Highest value on the x axis. Only applied if scaleMaxX = fixed

optional, float, default: 0.0

minY

Lowest value on the y axis. Only applied if scaleMinY = fixed

optional, float, default: 0.0

maxY

Highest value on the y axis. Only applied if scaleMaxY = fixed

optional, float, default: 0.0

minZ

Lowest value on the z axis. Only applied if scaleMinZ = fixed

optional, float, default: 0.0

maxZ

Highest value on the z axis. Only applied if scaleMaxZ = fixed

optional, float, default: 0.0

followX

If set to true, the graph follows new data with a fixed x axis scale. This is the same as selecting "follow new" data from the zoom dialog. The width of the x axis has to be defined by setting minX and maxX. Setting followX overrides scaleMinX and scaleMaxX and also forces partialUpdate to true.

added in 1.15 optional, boolean, default: false

mapWidth

Number of data points per line.

optional, integer, default: 0

showColorScale

Show or hide the color scale above the color plot

added in 1.19 optional, boolean, default: true

mapColor[N]

The n-th stop of the color scale for a map style, for any n from 1 upward (mapColor1, mapColor2, ...). The stops are read in order and the scale ends at the first number that is absent, so they must be numbered without gaps.

optional, color

interpolateMapColors

Interpolate area between data points. If disabled, phyphox expects the datapoints to be aligned on an evenly spaced rectangular grid and will show each datapoint as a rectangular "pixel" centered on the data point's x/y coordinate. Default behavior is to assign colors to the data point coordinates and interpolate colors in between.

added in 1.20 optional, boolean, default: true

pickLabel

Rename the "Pick data" button to show the user the purpose of the data picker (see data picker feature below).

added in 1.20 optional, translatable

<input axis="STRING" color="COLOR" lineWidth="FLOAT" style="STRING">TEXT</input>

Text content: Name of the data container to plot on this axis.

Several datasets are defined by several inputs: every y input is one dataset. When the file provides exactly as many x inputs as y inputs (z inputs do not count), they are matched 1-on-1 in order of appearance, regardless of interleaving - but write new files with each x before its y: the other orders are only supported for backwards compatibility and re-pair silently when an input is removed. With fewer x than y inputs, each y is plotted against the most recent preceding x input - so several datasets share one x by naming it once - or against its element index if no x input preceded it; any x input that no y input uses - trailing or shadowed - is an error. The per-dataset attributes color, lineWidth and style may sit on either input of a dataset; an attribute on the y input wins over one on its x input, a z input overrides both, and the graph-level attributes are the defaults for every dataset.

Attributes

axis

Which axis this container supplies.

required, one of x, y, z

color

Color of this dataset, overriding the graph's color.

optional, color

lineWidth

Line width of this dataset, overriding the graph's.

optional, float

style

Style of this dataset, overriding the graph's.

optional, one of lines, dots, hbars, vbars, map

Data pickeradded in 1.20

The graph can always be maximized by tapping it to reveal additional tools like zooming and a data picker. The data picker can be repurposed to allow users to pick and map data to measured data points. This can for example be used to pick a starting point for an automated data analysis or to match points to reference values for a calibration process. You can define how many x, y and z values (in the case of a color map plot) the user can pick, label the purpose of each pick and map it to data containers. Optionally, you can also request a value input from the user to map data points to calibration values. Finally, you can also rename the "pick data" button to reflect the use case for the data picker (see the "pickLabel" attribute of the graph above).

The data picker is configured by adding outputs that are linked to the target data containers. Here is the most basic example, allowing the user to pick a single x value:

<graph label="Graph title"  pickLabel="Pick X" ...>
  <input axis="x">datax</input>
  <input axis="y">datay</input>
  <output axis="x" label="Offset X">picked</output>
</graph>

This example renames the pick mode to "Pick X", and if the user picks a data point, they will see an additional button "Offset X" as defined by the label-attribute of the output. If the user presses that button, the data-container "picked" will receive the x value of the selected data point.

In addition to picking a point, the user can be allowed to map a value to the point:

<graph label="Graph title"  pickLabel="Pick X" ...>
  <input axis="x">datax</input>
  <input axis="y">datay</input>
  <output axis="x" label="Offset X">picked</output>
  <output axis="xcal" label="Enter a value to assign to your selected point">assigned</output>
</graph>

This example is identical to the previous one, except for having a second output that is assigned to the axis "xcal". This is used together with the axis="x" output and changes the behavior such that when the user presses the "Offset X" button, they will be prompted to enter a value. The label of the xcal output is shown as a prompt and when the user confirms their input, the data-container "picked" receives the x value of the selected point and "assigned" receives the entered value.

You can define an arbitrary number of outputs, assigning them to the axes "x", "y" or "z". Each will show up as a button to the user with the defined "label" of the output. Also, for each axis an additional "xcal", "ycal" or "zcal" can be defined, which will affect the previously defined "x", "y" or "z" output. The following example shows a configuration that allows the user to assign two x values for a spectrum calibration:

<graph label="Graph title"  pickLabel="Calibrate" ...>
  <input axis="x">datax</input>
  <input axis="y">datay</input>
  <output axis="x" label="Calibration point 1">cal_x1</output>
  <output axis="xcal" label="Assigned wavelength in nm">cal_lambda1</output>
  <output axis="x" label="Calibration point 2">cal_x2</output>
  <output axis="xcal" label="Assigned wavelength in nm">cal_lambda2</output>
</graph>

A formula node can then be used to calculate a linear calibration from these two points and generate a new x data set to show a calibrated version in another graph.

<output axis="STRING" label="STRING">TEXT</output>

Text content: Name of the data container receiving the picked coordinate.

Attributes

axis

Which coordinate of the picked point to write. The cal variants modify the preceding output of the same axis: instead of writing immediately, the user is prompted for a value, the point's coordinate goes to the plain output and the entered value to the cal one. That is how two points are mapped to reference values for a calibration.

required, one of x, xcal, y, ycal, z, zcal

label

Text of the button offered for this output once a point is picked.

optional, translatable

Other graph types

Available since phyphox file format 1.7 (phyphox 1.1.0)

Bar charts

Since file format 1.7, you can also use bar charts by setting style to "hbars" or "vbars" for horizontal or vertical bars, respectively. For bar charts, you also define x and y values as you do for line charts, but the x value represents the left edge of a bar while y represents its height (for horizontal bars, y defines the bottom and x the width). Each bar ends where the next one begins and the last height will not be drawn as it only marks the end of the previous bar. Therefore, to draw 4 bars, you need to provide 5 value pairs.

For bar charts, the line width describes the gap between bars. A line width of 1 means that there is no gap, while a line width of 0.5 means that the bars only occupy 50% of the available width (they will be centered in this space).

Color map charts

File format 1.7 also introduces color map charts (also known as false color plots). These do not plot y values as a function of x values, but z values as a function of x and y. z is encoded as a color and the result is a map of different colors.

So, you need to provide three datasets, "x", "y" and "z". This is done similarly to the traditional 2D plots:

<graph label="Fourier Transform" logZ="true" labelX="Frequency" unitX="Hz" labelY="Time" unitY="s" labelZ="FFT Mag" unitZ="a.u." aspectRatio="1" style="map" mapWidth="256" partialUpdate="true">
  <input axis="x">fmap</input>
  <input axis="y">tmap</input>
  <input axis="z">fftmap</input>
</graph>

The example shows the color map plot of the "Audio Spectrum" experiment. "fmap" contributes the frequencies for the x axis, "tmap" the timestamps for the y axis and "fftmap" the amplitudes that define the colors. Note that all three buffers need to provide the same number of values and that their indices need to match. There is no requirement that each value of each row has exactly the same value, so the value has to be provided for every single data point. However, you cannot just provide arbitrarily distributed data points.

The color map creates a lattice from the provided points, which is then colored. For this, an additional parameter "mapWidth" is set for the graph-Tag, which defines how many data points form a row. The datapoints within this row may be at slightly varied locations, which will be displayed correctly (although the remote interface will not show their location correctly), but very large deviations can lead to a distorted image as the connection to the next row won't match up. If you need to plot random data pairs, you might want to check out the map analysis module.

Also note that, due to the typical use of such color maps, the attribute "partialUpdate" (see above) now applies to the y axis, which needs to be monotonic, instead of the x axis.

The colors of the map are set with the mapColor[N] attributes (mapColor1, mapColor2, ..., see the attribute list above). A stop that is present but does not name a valid color (a named phyphox color or a six-digit hex RGB value, optionally prefixed with #) is an error and the experiment will not load — the same strictness that applies to every color attribute in the format.

You can also define your own color palette. Phyphox uses a black-orange-white gradient by default, but introducing more colors can be very helpful to improve contrast. Colors are simply defined as a series of colors that are spread across the z range:

<graph label="Normalized history" labelX="distance" unitX="cm" labelY="time" unitY="s" labelZ="A" unitZ="a.u." aspectRatio="1" style="map" mapWidth="1200" mapColor1="000000" mapColor2="0000ff" mapColor3="00ffff" mapColor4="00ff00" mapColor5="ffff00" mapColor6="ff0000" mapColor7="ffffff" partialUpdate="true">
  <input axis="x">distance_map</input>
  <input axis="y">time_map</input>
  <input axis="z">weighted_map</input>
</graph>

This example shows the colorful palette of the sonar experiment.

Multiple graphs

Since file format 1.7 (phyphox 1.1.0) you can also combine multiple graph types (except for the color map). To do so, you can simply define more than one dataset for x and y:

<graph label="Acceleration" labelX="t" unitX="s" labelY="a" unitY="m/s²" partialUpdate="true">
  <input axis="x" color="green">acc_time</input>
  <input axis="y">accX</input>
  <input axis="x" color="blue">acc_time</input>
  <input axis="y">accY</input>
  <input axis="x" color="yellow">acc_time</input>
  <input axis="y">accZ</input>
  <input axis="x" color="white">acc_time</input>
  <input axis="y">acc</input>
</graph>

This example just creates four line charts for the "multi" page of the raw accelerometer experiment.

How the input tags form datasets: every y input is one dataset (one curve). When a graph provides exactly as many x inputs as y inputs (z inputs do not count), they are matched 1-on-1 in their order of appearance, whatever the interleaving — so the n-th x belongs to the n-th y. Do not rely on this for new files: orders other than x-directly-before-its-y are supported for backwards compatibility only, and they are fragile — removing a single input from a y-first graph silently re-pairs the remaining datasets under the rules below, while the x-then-y style degrades gracefully. With fewer x than y inputs, each y is plotted against the most recent preceding x input — so several datasets can share one x axis by naming its data container once, before the first y — and a dataset with no preceding x at all is plotted against its element index. Any x input that no y input uses — trailing, or shadowed by a later x before any y consumed it — is an error, and every input must name its axis.

Per dataset you can override the graph-level color, lineWidth and style (as lines, dots, vbars or hbars) by applying these attributes to one of the dataset's input tags — it does not matter whether to the x or the y input; if both carry an attribute, the one on the y input wins, and an attribute on a z input overrides both. An x input shared by several datasets styles only the first dataset that uses it. Datasets without an explicit color cycle through six default colors (orange, green, blue, yellow, magenta, red, then repeating), while a color attribute on the graph tag itself colors every dataset the same.