Phyphox file format

From phyphox
Jump to navigation Jump to search

This page discusses technical details. There is a simpler and probably more convenient approach by using the visual experiment editor.

This page is highly technical and meant for advanced users who want to control every minute detail of their experiment. On this page you will learn, how the phyphox file format works and how to create a phyphox experiment - all you need is a text editor. Some experience about the XML format is recommended.

Contents

Structure

The phyphox format is based on xml. The entire experiment is encapsulated within a phyphox root tag. Within this block, there are multiple blocks which allow to define data-containers, inputs, outputs, translations, analysis etc. 

<phyphox version="1.0">
    <title>Experiment title</title>
    <category>Experiment category</category>
    <icon>
        ... Defines which icon should be shown ...
    </icon>
    <description>
        ... A description of the experiment ...
    </description>
    <translations>
        ... Translations into other languages than English ...
    </translations>
    <data-containers>
        ... Defines data buffers to hold sensor and result data ...
    </data-containers>
    <input>
        ... Inputs like sensors or the microphone ...
    </input>
    <output>
        ... Outputs like the speaker ...
    </output>
    <views>
        ... Different views, defining how the results are presented to the user ...
    </views>
    <analysis>
        ... All the math goes in here ...
    </analysis>
    <export>
        ... Export sets define how data-containers are grouped and named when exporting them to a file ...
    </export>
</phyphox>

Block: phyphox

The entire experiment is defined within the phyphox block. It has a single attribute, which is the version of the file format (not the version of the app). If the file format changes in future version, this version number will increase. If phyphox (the app) encounters a file version newer than what it can read, it will not load the file but ask the user to update the app.

Tag: Title

<title>TITLE</title>

The title of the experiment. This is just a simple string. Try to keep it short and concise.

Tag: State-Title

Available since phyphox file format 1.5 (phyphox 1.0.7)

<state-title>TITLE</state-title>

This should not be used for a experiment, which will be distributed. This tag contains the title given by the user when saving the state of an experiment. If this is set, the app will show this experiment in the saved-states section.

Tag: category

<category>CATEGORY</category>

The category of the experiment. This is just a simple string used by the app to group the experiments. Try to keep it short and concise.

Note that this can and should be translated if you use translations (see below) as the app uses the localized version of this string and cannot match your experiment to the default group if the category is given in a different language.

Tag: icon

<icon format="FORMAT">ICON</icon>

The icon of the experiment. The attribute format controls whether ICON is just a string or a base64 encoded image. If it is a string, phyphox will take the first three characters (using fewer characters is ok) and create a simple icon with these. If it is a base64-encoded image, phyphox will decode it and display the image.

We recommend to use a small PNG with few colors as an icon. There are various web-based tools to create a base64-encoded PNG from a PNG file.

format
Can be string or base64 and controls whether the icon should be interpreted as a string or as a base64 encoded image.
optional, default: string

Tag: description

<description>DESCRIPTION</description>

A description of the experiment. The first line should be a very short information of what the experiment does as this line will be shown in the experiment list. Any white spaces at the beginning and end of DESCRIPTION as well as in each line will be stripped.

Tag: link

<link label="LABEL">URL</link>

A link-Tag defines a link to some resource on the web. You may have multiple link tags in your phyphox file and they will be listed as a button each under the experiment description. When the user pushes the button, he will be redirected to the URL (usually in a web browser, but it might be a specific app for a specific URL - for example Youtube links usually open in the Youtube-App in Android).

Block: translations

The translation block may hold one or more translation block (note: singular), describing the translations of strings shown to the user. Any string outside the translations block should be in English and then translated to other languages from within the translations block. 

<phyphox version="1.0">
    <title>My experiment</title>
    <category>Example</category>
    ...
    <translations>
        <translation locale="de">
            <title>Mein Experiment</title>
            <category>Beispiel</category>
            <string original="Some string used in the experiment.">Ein im Experiment genutzter String.</string>
            ...
        </translation>
        <translation locale="fr">
            <title>Mon expérience</title>
            <category>Exemple</category>
            <string original="Some string used in the experiment.">Une chaîne de caractères utilisèe dans l'experiénce.</string>
            ...
        </translation>
    </translations>
    ...
</phyphox>

Block: translation

Each translation block holds all the translations for a single language. The attribute

locale
Defines the two-character iso language code for the translations within this language block. (for example "de" for German or "fr" for French)
required


Tag: title

<title>TITLE</title>

Localized version of the title tag in the phyphox-block (see above). If the user's locale matches the locale of the translation block, the title will be replaced by this entry.


Tag: category

<category>CATEGORY</category>

Localized version of the category tag in the phyphox-block (see above). If the user's locale matches the locale of the translation block, the title will be replaced by this entry. Note that phyphox will group experiments by the localized version of the category.

Tag: description

<description>DESCRIPTION</description>

Localized version of the description tag in the phyphox-block (see above). If the user's locale matches the locale of the translation block, the title will be replaced by this entry.


Tag: link

<link label="LABEL">URL</link>

This is the localized version of the link-Tag. For example, if you link to a Demo video in English with <link label="Demo">http://site.org/my/english/video</link> you can link to a German version in the translation block with <link label="Demo">http://site.org/my/german/video</link>

Tag: string

<string original="ORIGINAL">TRANSLATION</string>

Use the string-tag to translate any string shown to the user besides the title, description or category. If the text of a label, view etc. matches the string in ORIGINAL, phyphox will display TRANSLATION instead. (Of course, this only applies if the user's locale matches the translation locale.)

original
The string which should be translated with TRANSLATION. This has to be an exact match.
required

Block: data-containers

In data-containers all buffers are defined. Any input (sensors, microphone) write to these buffers, any analysis module performs its operations on these buffers, the output modules read from these buffers and the results are shown to the user from these buffers. The buffers connect every module of the experiment. 

<phyphox version="1.0">
    ...
    <data-containers>
        <container>Buffer 1</container>
        <container size="1000">Buffer 2</container>
        <container type="buffer">Buffer 3</container>
    </data-containers>
    ...
</phyphox>

Tag: container

<container size="INTEGER" init="FLOAT" static="BOOLEAN">NAME</container>

The container tag defines the name of a single data container. For now, the only container type is buffer, so the attribute type can be left out - It is only there for future new container types.

The buffer type is a queue of a fixed length. New data is appended until the buffer is full. If data is appended to a full buffer, old data is removed from the other end. Any module reading from the buffer will receive the whole data set. However, if the module only requires a single value, it may access the last added value directly.

The size can be set by the size attribute, which defaults to 1.

Infinite buffers are allowed and can be achieved by setting size to zero. However, you should be careful when using this. Never keep filling an infinite buffer if it is the base for complex analysis as this will lead to extreme load when the experiment runs for a long period. Also, infinite buffers are not allowed to hold the recording from an audio input.

type
The only type supported right now is buffer. This attribute can be ignored for now, but other container types may be added in the future.
optional, default: buffer
size
The size of the data-container. For the buffer type this is the number of values, the buffer can hold.
optional, default: 1
static
If set to true, the content of this buffer should only be written once. Analysis modules writing to this buffer will not execute if all output buffers are static to improve performance. This should be set if the content does not depend on measured data.
optional, default: false
init, Available since phyphox file format 1.3 (phyphox 1.0.4)
If set, the buffer will be initialized with the given value when loading the experiment as well as when clearing the data. If not set, the buffer will start empty. Since file format 1.5 (phyphox 1.0.7) you can also separate multiple values by comma to initialize a buffer with multiple values.

Block: input

The input block defines all hardware inputs such as sensors or the microphone used in the experiment. 

<phyphox version="1.0">
    ...
    <input>
        <sensor type="pressure">
            <output component="x">Pressure</output>
        </sensor>
        <sensor type="accelerometer" average="true" rate="0.5">
            <output component="x">AccX</output>
            <output component="y">AccY</output>
            <output component="z">AccZ</output>
            <output component="t">AccT</output>
        </sensor>
        <audio rate="48000">
            <output>recording</output>
        </audio>
    </input>
    ...
</phyphox>

Input module: sensor

<sensor type="TYPE" average="BOOLEAN" rate="FLOAT">
    <output component="x">BUFFER</output>
    ...
    <output component="t">BUFFER</output>
</sensor>

The sensor block defines a sensor as an input. The data will be written to the output buffers at the rate as it is provided from the sensor. Alternatively, you may define a different rate, in which case the latest reading is picked at the given rate. In addition you may turn on averaging in combination with the forced rate, in which case all data during the interval of the rate is averaged and only the average is written to the buffer.

Many sensors (accelerometer, magnetometer, gyroscope) are 3D sensors writing to a total of four buffers (x, y, z and timestamp t), but you do not need to attach a buffer to all outputs. Also some sensors are only 1D (pressure, light) and will only fill the x buffers. The outputs are mapped to data-containers by simple output-tags. Each requires a component attribute set to x, y, z or t to map the data o the data-container.

Since file format version 1.4 (phyphox 1.0.6) there is another output abs which gives the absolute (sqrt(x*x+y*y*z*z)) for 3D sensor data.

Since file format version 1.5 (phyphox 1.0.7) there is another output accuracy which gives information about the current accuracy. Typically, "-1" means that the sensor is uncalibrated (which might be an error state), "0" means that uncalibrated raw data is presented (but this is expected) and positive values represent accuracy in a way specific to the sensor. This is currently only used by the magnetometer, which encodes its accuracy as 1 low, 2 medium and 3 high.

If a sensor is not available on the device, the experiment will notify the user and refuse to work.

Note, that the somewhat cumbersome names for "acceleration with g" and "acceleration (without g)" have been chosen to aid students in understanding the data given by these sensors. But internally we stick to the names commonly used in the Android as "accelerometer" and "linear_acceleration". Usually, "accelerometer" (the one with g) is a physical sensor which measures the acceleration force applied to a sample mass (in form of a MEMS device), so it will give a constant acceleration of 9.81 m/s² for a resting device (hence our descriptive name "with g"). In contrast, "linear_acceleration" is usually just a virtual sensor, which may use additional sensors to remove the earth's acceleration (hence our descriptive annotation "without g") to report the actual acceleration of the phone in the reference system of the user. So "linear_acceleration" will report zero acceleration when the phone is resting and moved at a constant speed.

type
Defines the sensor type to be used. Allowed values:
accelerometer
The accelerometer in m/s². This gives the earth's acceleration when the device is resting. (Usually named "acceleration with g" in phyphox)
linear_acceleration
A virtual sensor giving the actual acceleration of the device. Should report zero when the device is resting. (Usually named "acceleration (without g)" in phyphox)
magnetic_field
Readings from the magnetometer in µT
gyroscope
Readings from the gyroscope in rad/s.
light
The illuminance from the light sensor in lx
pressure
The air pressure from the barometer in hPa
required
rate
The rate at which sensor data will be provided in Hz. A value of 0.0 means "as fast as possible". Note that the maximum rate of a sensor is device-specific and will limit the rate set with this attribute.
optional, default: 0.0
average
If set to true, instead of just giving the latest reading at the defined rate, the sensor data will be averaged over a period of the rate. This only makes sense if a rate is set, which is lower than the maximum rate the device can achieve.
optional, default: false

Input module: audio

<audio rate="INTEGER">
    <output>BUFFER</output>
</audio>

The audio tag defines audio as a data source (i.e. a microphone). Phyphox will record continously and write the recording to the buffer at the beginning of an analysis execution (see analysis block). The target buffer is defined with a simple output-tag.

The default recording rate is 48kHz, but can be changed using the rate attribute (in Hz). However, this is not recommended if the experiment targets a wide audience since supported recording rates are very device specific.

rate
The recording rate in Hz.
optional, default: 48000


Block: output

The input block defines all hardware outputs such as the speaker used in the experiment. 

<phyphox version="1.0">
    ...
    <output>
        <audio rate="48000" loop="true">
            <input>waveform</input>
        </audio>
    </output>
    ...
</phyphox>

Output module: audio

<audio rate="INTEGER" loop="BOOLEAN">
    <input>BUFFER</input>
</audio>

The audio tag defines audio as an output (i.e. a speaker). At the end of an analysis period phyphox will write the input buffer to an internal audio buffer and start the playback, so the sound is played after each analysis execution. The input target is defined with a simple input-tag. If the input buffer is static, phyphox will only write it once to the audio buffer, but still play it after each analysis execution.

If the loop attribute is set to true, the playback is looped. If the input buffer is not entirely filled, it will be written periodically until the audio buffer is full. This repeated data should not be played as the looping is done by defining a loop over the length of the buffer data. However, if the loop interval becomes too short, some devices refuse to loop over such short ranges and in this case, the loop will happen because of the repeated data. This will lead to irregular loops if the buffer length is not a multiple of the written data.

The default playback rate is 48kHz, but can be changed using the rate attribute (in Hz). However, this is not recommended if the experiment targets a wide audience since supported playback rates are very device specific.

rate
The recording rate in Hz.
optional, default: 48000
loop
Loop playback
optional, default: false

Block: analysis

The analysis block describes all the math required for the experiment. Each element within this block is executed consecutively and usually reads from a data-container, performs a mathematical operation on the data and writes the results to another data-container.

In most experiments the analysis block is executed in a loop, so the experiment data is analysed as fast as possible. However, if you need to aquire a certain amount of data first (mostly when recording from the microphone) or if the results only change if the user changes a parameter, you can define the attributes sleep, dynamicSleep and/or onUserInput to pause the analysis loop.

sleep
The minimum time in seconds before the whole analysis block is executed again after the last execution has finished. Decimal values allowed.
optional, default: '0.0' (immediately)
dynamicSleep
The minimum time in seconds before the whole analysis block is executed again after the last execution has finished. This refers to a buffer, so the sleep time can be set by the analysis result. If the buffer is empty, the value from sleep is used instead. Available since phyphox file format 1.5 (phyphox 1.0.7)
optional, default: '0.0' (immediately)
onUserInput
If true, the analysis block will not be executed again unless the user changes the content of an input view.
optional, default: 'false'
<phyphox version="1.0">
    ...
    <analysis sleep="2.0" dynamicSleep="buffer" onUserInput="false">
        <add>
            <input>Buffer1</input>
            <input type="buffer">Buffer 2</input>
            <output>sumBuffer</output>
        </add>
        <divide>
            <input type="value" as="dividend">1</input>
            <input as="divisor">sumBuffer</input>
            <output>inverseSum</output>
        </divide>
    </analysis>
    ...
</phyphox>

Analysis modules in general

<input type="TYPE" as="AS">BUFFER/VALUE</input>
<output as="AS">BUFFER</output>

Almost all analysis modules take inputs and write their results to an output buffer. All inputs and outputs are defined as input and output tags within the analysis module. While the output always has to be a data-container, the input may also be a floating point value which can be defined by setting the attribute type to value. If type is not set, it defaults to buffer and the given name has to match a data-container. Additionally, the input may be set to the type empty, which is similar to value but represents a constant empty buffer. This only makes sense and is supported for few modules and will be noted there.

Both, inputs and outputs, can be given a specific function by the as attribute. For many modules this attribute can be omitted if it is obvious. For example the add module takes an arbitrary number of inputs in an arbitrary order (a+b equals b+a), but the subtract module needs an explicit mapping for the minuend and the subtrahend (a-b does not equal b-a). Similarly, a single output does not need to be mapped, while multiple outputs (for example value and position of a maximum in the max module) need to be mapped.

Additionally, some analysis modules take parameters that are not dynamically defined, but as an attribute to the analysis module tag. As an example, the threshold module searches the point at which the input values cross a given threshold and the attribute falling can switch it to look for a crossing from larger to smaller values.

The specific mappings, attributes and functionality of the analysis modules are documented below.

input-tag
Attributes for input tags:
as
The mapping of the input to a function
optional or required depending on the module
type
Can be set to buffer or value and indicates whether the content of the the tag is a numeric value or refers to a data-container
optional, default: buffer
clear
false will mean, that the buffer retains its data after reading. If set to false, the buffer is cleared after reading, which can be used to process each dataset from an input only once.
optional, default: true
output-tag
Attributes for output tags:
as
The mapping of the input to a function
optional or required depending on the module
clear
false will mean, that the buffer retains its data (from another module writing to this buffer or from the previous analysis run) and new data is appended. true will clear the buffer first.
optional, default: true

Analysis module: timer

Simple module which just outputs the (fractional) seconds that have past since the first analysis run started and the current analysis run began.


out
output
as not required


Analysis module: add

Calculates the sum of all inputs element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

summand
input
as not required
Number of inputs: At least one
sum
output
as not required

Analysis module: subtract

Calculates the difference of multiple subtrahends from a single minuend element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

For this simple function you can leave out the as attribute. If you do so, the first input will be used as minuend and all subsequent values as subtrahends.

minuend
input
as not required, but order matters if left out
Number of inputs: Exactly one
subtrahend
input
as not required, but order matters if left out
Number of inputs: Arbitrary
difference
output
as not required

Analysis module: multiply

Calculates the product of all inputs element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

factor
input
as not required
Number of inputs: At least one
product
output
as not required

Analysis module: divide

Calculates the quotient of multiple divisors from a single dividend element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

For this simple function you can leave out the as attribute. If you do so, the first input will be used as dividend and all subsequent values as divisors.

dividend
input
as not required, but order matters if left out
Number of inputs: Exactly one
divisor
input
as not required, but order matters if left out
Number of inputs: Arbitrary
quotient
output
as not required

Analysis module: power

Calculates the power of a base and an exponent element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

base
input
as required
Number of inputs: Exactly one
exponent
input
as required
Number of inputs: Exactly one
power
output
as not required

Analysis module: gcd (greatest common divisor)

Calculates the greatest common divisor of two inputs element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

value
input
as not required
Number of inputs: Exactly two
gcd
output
as not required

Analysis module: lcm (least common multiple)

Calculates the least common multiple of two inputs element-wise and writes it to a single output buffer. This module will write as many values as there are values in the biggest input buffer. If a buffer is shorter than the others (especially if one input is a single value), its last value will be repeated.

value
input
as not required
Number of inputs: Exactly two
lcm
output
as not required


Analysis module: abs (absolute)

Calculates the absolute value of a single input element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

value
input
as not required
Number of inputs: Exactly one
abs
output
as not required

Analysis module: round

Available since phyphox file format 1.5 (phyphox 1.0.7)

Round the values from the single input element-wise and writes the results to a single output buffer. This module will write as many values as there are values in the input buffer. By default it will round to the nearest integer. The attributes ceil and floor can change that to the nearest larger integer or the nearest smaller integer.

floor
attribute
optional, default: false
ceil
attribute
optional, default: false
value
input
as not required
Number of inputs: Exactly one
round
output
as not required

Analysis module: log

Available since phyphox file format 1.5 (phyphox 1.0.7)

Calculates the natural logarithm of a single input element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

value
input
as not required
Number of inputs: Exactly one
log
output
as not required

Analysis module: sin

Calculates the sine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the deg attribute.

deg
attribute, Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: false
value
input
as not required
Number of inputs: Exactly one
sin
output
as not required


Analysis module: cos

Calculates the cosine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the deg attribute.

deg
attribute, Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: false
value
input
as not required
Number of inputs: Exactly one
cos
output
as not required

Analysis module: tan

Calculates the tangens of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the deg attribute.

deg
attribute, Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: false
value
input
as not required
Number of inputs: Exactly one
tan
output
as not required

Analysis module: asin

Calculates the inverse sine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the deg attribute.

deg
attribute, Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: false
value
input
as not required
Number of inputs: Exactly one
asin
output
as not required


Analysis module: acos

Calculates the inverse cosine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the deg attribute.

deg
attribute, Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: false
value
input
as not required
Number of inputs: Exactly one
acos
output
as not required

Analysis module: atan

Calculates the inverse tangens of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the deg attribute.

deg
attribute, Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: false
value
input
as not required
Number of inputs: Exactly one
atan
output
as not required

Analysis module: atan2

Calculates the two-argument variant of the inverse tangens (corresponding to atan(y/x)) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer. The module will calculate in radians unless degrees are specified using the deg attribute.

deg
attribute, Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: false
y
input
as not required
Number of inputs: Exactly one
x
input
as not required
Number of inputs: Exactly one
atan2
output
as not required

Analysis module: sinh

Calculates the hyperbolic sine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

value
input
as not required
Number of inputs: Exactly one
sinh
output
as not required


Analysis module: cosh

Calculates the hyperbolic cosine of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

value
input
as not required
Number of inputs: Exactly one
cosh
output
as not required

Analysis module: tanh

Calculates the hyperbolic tangens of a single input (in radians) element-wise and writes it to a single output buffer. This module will write as many values as there are values in the input buffer.

value
input
as not required
Number of inputs: Exactly one
tanh
output
as not required

Analysis module: first

Retrieves the first entry of each buffer and appends it to each output buffer.

value
input
as not required
Number of inputs: At least one
first
output
as not required
Multiple may be defined!

Analysis module: count

Available since phyphox file format 1.2 (phyphox 1.0.3)

Returns the number of values in the input buffer

buffer
input
as not required
Number of inputs: Exactly one
count
output
as not required

Analysis module: max

Returns the maximum and its position. This module takes at least one input y and looks for the maximum of this buffer, but may also take a second input x. If x is defined, it will return the position of this maximum in terms of the associated x value. If x is not defined, position will be the index of the maximum.

If you want to find multiple local maxima, you can set the attribute "multiple" to true. In this case a third input may be used, which provides a threshold. The algorithm will split the data into sets that are entirely above the threshold and return a maximum and position for each set.

This module will return exactly one value per call if multiple is deactivated (default).

x
input
as required
Number of inputs: One or none
y
input
as required
Number of inputs: Exactly one
threshold
input
as required
Number of inputs: One or none
max
output
as required
position
output
as required

Analysis module: min

Returns the minimum and its position. This module takes at least one input y and looks for the minimum of this buffer, but may also take a second input x. If x is defined, it will return the position of this minimum in terms of the associated x value. If x is not defined, position will be the index of the minimum.

If you want to find multiple local minima, you can set the attribute "multiple" to true. In this case a third input may be used, which provides a threshold. The algorithm will split the data into sets that are entirely above the threshold and return a minimum and position for each set.

This module will return exactly one value per call if multiple is deactivated (default).

x
input
as required
Number of inputs: One or none
y
input
as required
Number of inputs: Exactly one
threshold
input
as required
Number of inputs: One or none
min
output
as required
position
output
as required

Analysis module: threshold

This module takes at least one input y and looks for position at which the values cross a given threshold. the input threshold is interpreted as a single value (last added element). This module may also take a third input x. If x is defined, it will return the position of the crossing in terms of the associated x value. If x is not defined, position will be the index of the crossing.

You can also define the attribute falling as true to search for a crossing from larger to smaller values.

This module will return exactly one value per call.

falling
attribute
optional, default: false
x
input
as required
Number of inputs: One or none
y
input
as required
Number of inputs: Exactly one
threshold
input
as required
Number of inputs: One or none (defaults to 0.0)
position
output
as not required

Analysis module: append

This module appends all the values of the input buffers to a single output buffer. The order of the buffers will match the order their values appear in the output buffer. This module will return as many value as the sum of the input buffer sizes.

in
input
as not required
type="empty" allowed
Number of inputs: At least one
out
output
as not required

Analysis module: fft

This module will perform a fast fourier transform of a complex input and will write the complex result to the output buffers. For input and output the complex data is defined by two buffers re and im corresponding to the real and imaginary part. The imaginary buffer is optional and will be filled with zeros if omitted. This module will return as many values as provided by the input buffer.

re
input
as not required
Number of inputs: Exactly one
im
input
as required
Number of inputs: One or none
re
output
as not required
im
output
as required

Analysis module: autocorrelation

This module will calculate the autocorrelation. It takes at least one input buffer y, but can take a second input x as well. If x is omitted, it will be filled with indices. Additionally, single value inputs minX and maxX can be set as well. These limit the x range over which the autocorrelation is calculated to improve performance. The module will return as many values as provided by the input buffer and fill the output buffer y with the normalized autocorrelation of the y input buffer. The x output buffer will be filled with the relative x of the autocorrelation based on the x input buffer.

x
input
as required
Number of inputs: One or none
y
input
as required
Number of inputs: Exactly one
minX
input
as required
Number of inputs: One or none
maxX
input
as required
Number of inputs: One or none
y
output
as required
x
output
as required


Analysis module: periodicity

Mathematically, this module is similar to the autocorrelation module, but is meant to analyse large amounts of data in small subsets. The output is the periodicity of each subset and the x location of this subset. The typical use is a time-based frequency analysis. You put in the recording of a (single frequency) musical melody and the output will be the frequencies as a function of time.

The x and y inputs take the data to be analyzed and you also need to define a step size dx in units of samples. This means, that the data will be split into subsets [0..dx-1], [dx..2dx-1], [2dx..3dx-1], etc. Optionally, you may define an overlap, describing the number of samples taken into the calculation from before and after the subset (hence, used in multiple subsets).

The algorithm expects the autocorrelation to be periodic. It looks for the first offset i0 at which it becomes negative and then searches for a maximum in the next positive period at 3*i0..5*i0. You may define an offset range (in samples) by setting min and/or max. If you do so, the algorithm will just search for a maximum between min and max. If you can set this range quite narrow, this will speed up the calculation vastly, but if min/max cover multiple periods, this will quite certainly be slower and give wrong results.

While all parameters are defined in samples, the resulting output time will be in units of the input x.

x
input
as required
Number of inputs: Exactly one
y
input
as required
Number of inputs: Exactly one
dx
input
as required
Number of inputs: Exactly one
overlap
input
as required
Number of inputs: One or none
min
input
as required
Number of inputs: One or none
max
input
as required
Number of inputs: One or none
time
output
as required
period
output
as required

Analysis module: differentiate

Performs a simple differentiation of a single input by calculating the difference of consecutive elements. It will write the result to the output buffer with exactly one value less than there are values in the input buffer.

in
input
as not required
Number of inputs: Exactly one
out
output
as not required

Analysis module: integrate

Performs a simple integration of a single input by summing all elements and returning each step of the summation as a value. It will write as many values as there are values in the input buffer. So, if the input is a three-value array [v1, v2, v3], the output will be [v1, v1+v2, v1+v2+v3].

in
input
as not required
Number of inputs: Exactly one
out
output
as not required

Analysis module: crosscorrelation

This module will calculate a crosscorrelation of two inputs. It will only calculate the part of the crosscorrelation for which the smaller buffer is entirely covered by the larger one. So with one input buffer of size n and one input of size m it will return exactly abs(m-n) values. If you need the crosscorrelation of two buffers of similar size, you will need to pad one of them with zeros first.

in
input
as not required
Number of inputs: Exactly two
out
output
as not required

Analysis module: gausssmooth

This module will smooth the data provided from the only input. The data of each point will be calculated from neighbouring points with a gaussian distribution. The width of this distribution can be controlled by the attribute sigma and is interpreted in terms of value indices. This module will output as many values as there are values in the input buffer.

sigma
attribute
optional, default: 3.0
in
input
as not required
Number of inputs: Exactly one
out
output
as not required

Analysis module: match

This module takes multiple inputs and match valid values to the same number of outputs. The module will go through all inputs simultaneously and only return those value for which all inputs have a finite value.

If for example input1 provides [1, 2, NaN, 4, 5] and input2 provides [11, +Inf, 13, 14], the result will be [1, 4] for output1 and [11, 14] for output2. The other value pairs (more than two inputs are allowed though) were filtered as one of both inputs was infinite, not a number ("NaN") or just did not have any more values.

in
input
as not required
Number of inputs: At least one
out
output
as not required
Multiple may be defined!


Analysis module: rangefilter

This module takes multiple inputs and allows to set min and max limits for each of them. The module will go through all inputs simultaneously and only return those value for which all inputs fall within their set min and max range. If one input is shorter than the others, its values are set to NaN and will not trigger the filter.

Min and max have to be defined immediately after the corresponding input and are treated as a single value (last value for buffers). The outputs correspond to the order of the inputs. Here multiple outputs can be defined with the same name!

In the following example in1 will trigger the filter if not in the range of 0 and 42, in2 will not trigger the filter at all (but if in1 or in3 trigger the filter only corresponding elements will be returned) and in3 will trigger the filter if the value is larger than the value in the buffer "limit". The results will be written to the buffers "out1", "out2" and "out3". 

<rangefilter>
    <input>in1</input>
    <input as="min" type="value">0</input>
    <input as="max" type="value">42</input>
    <input>in2</input>
    <input>in3</input>
    <input as="max">limit</input>
    <output>out1</output>
    <output>out2</output>
    <output>out3</output>
</rangefilter>
in
input
as not required
Number of inputs: At least one
min
input
as required
Number of inputs: One or none per in input. This always refers to the previously defined in buffer.
max
input
as required
Number of inputs: One or none per in input. This always refers to the previously defined in buffer.
out
output
as not required
Multiple may be defined!

Analysis module: subrange

This module takes multiple inputs and returns all values within a given index range. This is much faster than using the rangefilter module for this purpose. The range is set using the inputs from (inclusive) and to (exclusive). Optionally, instead of setting to, you can set length, defining the total number of values returned after from. 

<subrange>
    <input as="from" type="value">0</input>
    <input as="to">countBuffer</input>
    <input>in1</input>
    <input>in2</input>
    <output>out1</output>
    <output>out2</output>
</subrange>
from
input
as required
Number of inputs: One or none. Defaults to 0
to
input
as required
Number of inputs: One or none. Defaults to length of input
length
input
as required
Number of inputs: One or none. Defaults to length of input, supersedes to
in
input
as not required
Number of inputs: At least one
out
output
as not required
Multiple may be defined!

Analysis module: ramp

This module will create a ramp of values, i.e. a linear range of values. This is very usefull to create time bases for example for audio recordings. The module takes as inputs start, stop and the optional length. It will make that the first value is exactly start and the last value is stop. It will return length values or if length is not provided as many values as the size of the output buffer.

start
input
as required
Number of inputs: Exactly one
stop
input
as required
Number of inputs: Exactly one
length
input
as required
Number of inputs: One or none
out
output
as not required


Analysis module: const

This module will initialize a buffer to a constant value. Both inputs are optional and without any inputs it will fill the entire buffer with zero. If value is set, the buffer gets filled with this value and if length is set, only 'length values will be initialized. (This is usefull in combination with the append module to zero-pad a buffer.)

value
input
as required
Number of inputs: One or none
length
input
as required
Number of inputs: One or none
out
output
as not required

Analysis module: average

Available since phyphox file format 1.2 (phyphox 1.0.3)

This module calculates the average of all values in the input buffer. Optionally (i.e. if the output is connected), the standard deviation is calculated as well (Corrected sample standard deviation).

buffer
input
as not required
Number of inputs: Exactly one
average
output
as required
stddev
output
as required

Analysis module: binning

Available since phyphox file format 1.2 (phyphox 1.0.3)

The binning module distributes the values from its input in into ranges (bins) and outputs a mapping of these ranges and the number of values in each of them. The bins are set to x0..x0+dx..x0+2dx..x0+3dx etc. Therefore x0 defines an offset of the bins and dx the size of each bin. x0 defaults to zero and dx to 1, so without these, the module defaults to binning to integer intervals.

The output can directly be used to display a histogram. binStarts will receive the starting values of each range (bin) while the count is written to binCounts.

in
input
as not required
Number of inputs: Exactly one
x0
input
as required
Number of inputs: One or none
dx
input
as required
Number of inputs: One or none
binStarts
output
as not required
binCounts
output
as not required

Analysis module: if

Available since phyphox file format 1.3 (phyphox 1.0.4)

The if module is the phyphox equivalent to the if-statement of a programming language. It takes two inputs a and b and will behave differently depending on the relation of the last values found there. By changing the attributes less, equal or greater, you can decide whether you are looking for a < b, a = b or a > b, respectively. If the relation is true, the if-module will write the data from the input true to the output, otherwise it will write the data from the input false. If you enable multiple attributes, the input true is used if any of them is fulfilled, so if you enable less and equal, a <= b will write the true input to the output, while a > b writes the false input.

Since version 1.4 (phyphox 1.0.6) you may set an input to be of the type empty. Effectively, this does not change the output as nothing is written, but can make sense in combination with setting the output to clear. In this case, the if module behaves somewhat special as it only clears its output if a matching input is connected. For example if you set the true input to empty, do not connect the false input and set the output to clear, it will only clear the output if the condition is true, but leaves it alone otherwise. This can be used as a reset condition. Note, that since the visual editor does not support reusing buffers, you probably cannot do this there in a reasonable way...

less
attribute
optional, default: false
equal
attribute
optional, default: false
greater
attribute
optional, default: false
a
input
as not required
Number of inputs: Exactly one
b
input
as not required
Number of inputs: Exactly one
true
input
as not required
type="empty" allowed
Number of inputs: Exactly one
false
input
as not required
type="empty" allowed
Number of inputs: Exactly one
out
output
as not required

Block: views

The views block may hold one or more view blocks (note: singular), describing the different layout groups (views), from which the user may choose to view the experiment data.

At least one view block is required! 

<phyphox version="1.0">
    ...
    <views>
        <view label="Pendulum">
            <value label="Frequency" unit="Hz">
                <input>frequencyBuffer</input>
            </value>
            <edit label="Length" unit="cm" factor="100" signed="false" default="50">
                <output>lengthBuffer</output>
            </edit>
            <info label="Example with user-input" />
        </view>
        <view label="Raw data">
            <graph label="Sensor data x" labelX="Time (s)" labelY="Amplitude">
                <input axis="x">timeBuffer</input>
                <input axis="y">sensorBuffer</input>
            </graph>
        </view>
    </views>
    ...
</phyphox>

Block: view

Each view-block groups display elements to present data to the user. The view block has a single attribute label displayed to the user to identify this view when the user switches views. The label should be short and concise.

label
The name identifying this view. Will be translated if a matching translation string is defined.
required

View-Element: info

<info label="INFOTEXT" />

The info element does not take any inputs or write to any outputs. It just displays a string defined as the label attribute.

label
The text to be displayed to the user
required

View-Element: separator

<separator color="ff7e22" height="0.1" />

The separator element does not take any inputs or write to any outputs. It just acts as a separator to give a visual aid in grouping other elements. It defaults to a very thin height of 0.1 (in units of text line heights) and a color matching the background color of the experiment screen. To achieve a margin between elements, you should set the height to 1 or to create a narrow line, set the color (as six-digit RGB hex value) and leave the height at 0.1 - optionally padded b two other separator elements.

color
The color of the whole (rectangular) element as six-digit RGB hex value
optional, default: background color
height
The height of the separator in text line heights
optional, default: 0.1

View-Element: value

<value label="LABEL" size="FLOAT" precision="INTEGER" scientific="BOOLEAN" unit="UNIT" factor="FLOAT">
    <input>BUFFER</input>
    <map min="DOUBLE" max="DOUBLE">STRING</map>
    <map>STRING</map>
</value>

The value element displays a single value to the user. If the input buffer contains more than one value, the latest value will be displayed. The input is defined by a simple input tag within the value block and needs to be a data-container (see above).

Since version 1.5 (phyphox 1.0.7) you can define range mappings with the map-tag. The map tag includes a string which will replace the number and unit that would be displayed otherwise. phyphox will test all mappings in the order they are given and replace the output with the first mapping that applies. A mapping applies if the value to be shown falls in the range given by the attributes min and max (inclusive). min and max can be left out and default to negative and positive infinity. So, a map-tag without any attributes acts as a catch-all case.

label
A label for this element
required
size
The size of the displayed value relative to the default font size. Label and unit will stay at their original size. Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: 1
precision
The number of digits after the decimal point.
optional, default: 2
scientific
If set to true, the value will be displayed in scientific notation (1.0e-3 instead of 0.001)
optional, default: false
unit
A unit to be displayed after the value
optional, default: no unit
factor
A factor to be applied to the value before displaying it. This is usually used for unit conversion. Example: The data is in meter, but should be displayed in cm. The factor would be 0.01
optional, default: 1.0

View-Element: graph

<graph label="LABEL" aspectRatio="FLOAT" style="STYLE" partialUpdate="BOOLEAN" history="INTEGER" labelX="LABELX" labelY="LABELY" logX="BOOLEAN" logy="BOOLEAN" xPrecision="INTEGER" yPrecision="INTEGER" minX="0" maxX="0" minY="0" maxY="0" scaleMinX="auto" scaleMaxX="auto" scaleMinY="auto" scaleMaxY="auto" lineWidth="1" color="ff7e22">
    <input axis="x">XBUFFER</input>
    <input axis="y">YBUFFER</input>
</value>

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 a 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. You can also define a single buffer, which will be used as y - The x axis will contain indices. In this case the axis attribute is not needed.

The resulting graph can be made up of lines (default) or dots (set attribute style to dots) and you can use the history attribute to show a history of plots. (see attriute description below)

The attributes 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 will then allow that only this data is transferred in the web-interface to save bandwidth.

label
A label for this element
required
apectRatio
The ratio of the total width of this element to the total height of this element in the view. (Including labels and axes)
optional, default: 3
style
If set to dots, the graph will not connect the values with lines.
optional, default: display 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, default: false
history
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.
optional, default: 1
labelX
The label of the x axis
optional, default: empty, but you should always label your axes...
labelY
The label of the y axis
optional, default: empty, but you should always label your axes...
logX
If set to true, the x axis will be on a logarithmic scale
optional, default: false
logY
If set to true, the y axis will be on a logarithmic scale
optional, default: false
xPrecision
The number of significant digits on the x axis. Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: 3
yPrecision
The number of significant digits on the y axis. Available since phyphox file format 1.2 (phyphox 1.0.3)
optional, default: 3
minX
Lowest value on the x axis. Only applied if scaleMinX = fixed
optional, default: 0
maxX
Highest value on the x axis. Only applied if scaleMaxX = fixed
optional, default: 0
minY
Lowest value on the y axis. Only applied if scaleMinY = fixed
optional, default: 0
maxY
Highest value on the y axis. Only applied if scaleMaxY = fixed
optional, default: 0
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, 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 minimum to maxX.
optional, 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, 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 minimum to maxY.
optional, default: auto
lineWidth
Width of the graph line relative to the default width
optional, default: 1
color
Color of the graph line
optional, default: phyphox orange

View-Element: edit

<edit label="LABEL" signed="BOOLEAN" decimal="BOOLEAN" min="FLOAT" max="FLOAT" unit="UNIT" factor="FLOAT" default="FLOAT">
    <output>BUFFER</output>
</value>

The edit element displays an edit box, which takes data from the user and writes it to a buffer. The output is defined by a simple output tag within the value block and needs to be a data-container (see above).

label
A label for this element
required
signed
If set to false the user may not enter negative numbers.
optional, default: true
decimal
If set to false the user may not enter decimal (i.e. non-integer) numbers.
optional, default: true
min
The minimum value allowed. Disable by not setting this attribute. Available from phyphox file format 1.1 (phyphox 1.0.2).
optional, default: disabled
max
The maximum value allowed. Disable by not setting this attribute. Available from phyphox file format 1.1 (phyphox 1.0.2).
optional, default: disabled
unit
A unit to be displayed after the value
optional, default: no unit
factor
A factor to be applied to the value before displaying it. This is usually used for unit conversion. Example: The data is in meter, but should be displayed in cm. The factor would be 0.01
optional, default: no unit
default
The default value of the edit box. The experiment will start with this value.
optional, default: 0.0


View-Element: button

Available since phyphox file format 1.3 (phyphox 1.0.4) 

<button label="LABEL">
    <input>BUFFER1</input>
    <output>BUFFER1</output>
    <input type="value">42</input>
    <output>BUFFER2</output>
    <input type="empty" />
    <output>BUFFER3</output>
</button>

The button element displays a simple button, which interacts with the buffers outside the analysis cycle. Whenever the user presses the button, the last value from each inputs (which may be value types or data-containers) is written to each output (the first input is written to the first output, the second to the second and so on). Note, that this does not happen at a certain point during analysis, but between analysis cycles, independent of when the user pushes the button.

Since version 1.4 (phyphox 1.0.6) you may define empty inputs (type="empty"), effectively allowing to clear a buffer when pressing the button.

label
A label for this element
required

Block: export

The export block may hold one or more set blocks, grouping and naming multiple data-containers as a logical unit to be written to a file when the user wants to export the data. The user may choose from these sets and for example select if he wants only the raw data, the analysis results or everything in his exported file. 

<phyphox version="1.0">
    ...
    <export>
        <set name="Results">
            <data name="Frequency">frequency</data>
            <data name="Period">period</data>
        </set>
        <set name="Raw data">
            <data name="Time t (s)">accT</data>
            <data name="Acceleration x (m/s²)">accX</data>
            <data name="Acceleration y (m/s²)">accY</data>
            <data name="Acceleration z (m/s²)">accZ</data>
        </set>
    </export>
    ...
</phyphox>

Block: set

The set block will define a group of data-containers to be exported. The attribute name will be shown to the user as he may pick which of the sets should be exported. Also these sets may be represented in the final file. For example a CSV export results in a ZIP file containing a separate CSV files for each set. In another example a Excel export will contain a separate sheet for each set.

Tag: data

<data name="NAME">BUFFER</data>

Within each set, you can define multiple data enties. Each of them maps a data-container to a name displayed to the user. Usually, this name is the column title corresponding to the data in the exported file.

name
A name describing the data
required
Retrieved from "http://phyphox.org/wiki/index.php?title=Phyphox_file_format&oldid=20204"