Difference between revisions of "Phyphox file format"

From phyphox
Jump to navigation Jump to search
 
(113 intermediate revisions by the same user not shown)
Line 44: Line 44:
 
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.
 
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 ===
+
'''Tag: Title'''
  
 
<code>
 
<code>
Line 52: Line 52:
 
The title of the experiment. This is just a simple string. Try to keep it short and concise.
 
The title of the experiment. This is just a simple string. Try to keep it short and concise.
  
−
=== Tag: category ===
+
'''Tag: State-Title'''
 +
 
 +
'''Available since phyphox file format 1.5 (phyphox 1.0.7)'''
 +
 
 +
<code>
 +
<state-title>TITLE</state-title>
 +
</code>
 +
 
 +
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'''
  
 
<code>
 
<code>
Line 62: Line 72:
 
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.
 
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 ===
+
'''Tag: icon'''
  
 
<code>
 
<code>
Line 76: Line 86:
 
: ''optional'', default: ''string''
 
: ''optional'', default: ''string''
  
−
=== Tag: description ===
+
'''Tag: color'''
 +
 
 +
<code>
 +
<color>COLOR</color>
 +
</code>
 +
 
 +
The base color for the experiment. This is used as a background of the icon (if a text-based icon is used or if it has a transparent background) and for the label of the category. If a category contains experiments with different colors, the most common color is used.
 +
 
 +
Color can be defined as a 6-digit hex value or as one of the named [[Colors]].
 +
 
 +
'''Tag: description'''
  
 
<code>
 
<code>
Line 83: Line 103:
  
 
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.
 
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'''
 +
 +
<code>
 +
<link label="LABEL" highlight="false">URL</link>
 +
</code>
 +
 +
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). If the attribute ''highlight'' is set to true, the link will also be featured in the experiment menu. (Note, that the highlight attribute is meant to highlight especially relevant links, like instructions for the experiment. Its actual implementation, i.e. the way a link is "highlighted" might change in newer versions.)
  
 
== Block: translations ==
 
== 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.
+
The translations block may hold one or more ''translation'' (note: singular) blocks, describing the translations of strings shown to the user. Any string outside the translations block is considered to be in English and then translated to other languages from within the translations block, unless a different global language has been defined in the tag of the phyphox-block or if English appears explicitly as a translation block. If English is used in a translation block and no language has been defined in the phyphox-block, the text outside the translation block should be treated as a placeholder.
  
 
  <nowiki>
 
  <nowiki>
Line 120: Line 148:
  
  
−
=== Tag: title ===
+
'''Tag: title'''
  
 
<code>
 
<code>
Line 129: Line 157:
  
  
−
=== Tag: category ===
+
'''Tag: category'''
  
 
<code>
 
<code>
Line 137: Line 165:
 
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.
 
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 ===
+
'''Tag: description'''
  
 
<code>
 
<code>
Line 146: Line 174:
  
  
−
=== Tag: string ===
+
'''Tag: link'''
 +
 
 +
<code>
 +
<link label="LABEL">URL</link>
 +
</code>
 +
 
 +
This is the localized version of the link-Tag. For example, if you link to a Demo video in English with
 +
<code>
 +
<link label="Demo">http://site.org/my/english/video</link>
 +
</code>
 +
you can link to a German version in the translation block with
 +
<code>
 +
<link label="Demo">http://site.org/my/german/video</link>
 +
</code>
 +
 
 +
'''Tag: string'''
  
 
<code>
 
<code>
Line 177: Line 220:
  
 
<code>
 
<code>
−
<container size="INTEGER" static="BOOLEAN">NAME</container>
+
<container size="INTEGER" init="FLOAT" static="BOOLEAN">NAME</container>
 
</code>
 
</code>
  
Line 185: Line 228:
  
 
The size can be set by the ''size'' attribute, which defaults to 1.
 
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
 
;type
Line 195: Line 240:
 
: 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.
 
: 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
 
: ''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 ==
 
== Block: input ==
Line 220: Line 267:
 
</phyphox>
 
</phyphox>
 
</nowiki>
 
</nowiki>
 +
 +
=== Input module: audio ===
 +
 +
<nowiki>
 +
<audio rate="INTEGER" append="false">
 +
    <output>BUFFER</output>
 +
    <output component="rate">BUFFER</output>
 +
</audio>
 +
</nowiki>
 +
 +
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. Also, the rate you set is not guaranteed. Instead you should read the actual rate from the rate output (see example above) and use that for any calculations that use a time base. Note that the rate output is written independently from the recording output (mostly when the rate changes, which usually only should happen if the audio setup changes). Therefore you should not delete this buffer while reading it. The rate output is '''available since phyphox file format 1.6 (phyphox 1.0.10)'''
 +
 +
;rate
 +
: The recording rate in Hz.
 +
: ''optional'', default: 48000
 +
;append
 +
: Append data to the output buffer instead of only offering new data since the last analysis cycle. '''Available since file format 1.16 (phyphox version [[Version_history#1.1.12|version 1.1.12]]).'''
 +
: ''optional'', default: false (buffer contains only new data)
 +
 +
=== Input module: bluetooth ===
 +
 +
'''Available since phyphox file format 1.7 (phyphox 1.1.0)'''
 +
 +
The bluetooth block defines an input from a Bluetooth Low Energy device. Please refer to the documentation on the [[Bluetooth Low Energy]] interface in phyphox for details.
 +
 +
 +
=== Input module: depth ===
 +
 +
'''Available since phyphox file format 1.14 (phyphox 1.1.10)'''
 +
 +
<nowiki>
 +
<depth mode="AGGREGATIONMODE" x1="FLOAT" x2="FLOAT" y1="FLOAT" y2="FLOAT" smooth="BOOLEAN">
 +
    <output component="z">BUFFER</output>
 +
    <output component="t">BUFFER</output>
 +
</depth>
 +
</nowiki>
 +
 +
Get a depth measurement from the depth sensor, which is typically a dedicated optical sesor as part of the camera array. On iOS, this type of sensor is called "LiDAR", while on Android you usually have to look for "ToF". Both systems have very different APIs to access this data with various advantages and drawbacks:
 +
 +
On iOS we access the LiDAR sensor through ARkit, which is the framework for augmented reality applications. The depth data is almost perfectly aligned with the camera image, but it is not raw data from the sensor, but processed and remapped for AR applications. Therefore, the data might have been fused with depth data derived from the normal color camera (for example depth estimation from parallax effects). Newer iOS devices also feature a depth sensor on the front, which is designed for FaceID, but this is available through an entirely different API and may be supported by phyphox in the future. (Details on Apple's API can be found at https://developer.apple.com/documentation/arkit/ardepthdata)
 +
 +
On Android we decided against using ARcore, Google's augmented reality framework, as a more direct API is available and dependencies on Google Services could be avoided in favor of platforms that do not have Google support. Here we use the camera2 API to access the sensor data, which has the benefit that we do not expect any fusion with AR data. However, the disadvantage is that the depth data has not been remapped to align with the regular camera image and you will experience an offset, which in particular will depend on the viewing distance as camera and sensor are placed at a distance in the phone's case. The camera2 API allows for accessing front and back facing depth sensors, but be aware that some phones advertise a ToF sensor for camera autofocus without exposing its data through the camera2 API. (Details on the camera2 API can be found at: https://developer.android.com/reference/android/hardware/camera2/package-summary)
 +
 +
Typically the user selects an area within the camera/depth data (which can be preset using the attributes x1, x2, y1, y2) that is aggregated into one depth value per frame. For each frame a pair of an aggregated depth value "z" and the corresponding timestamp "t" will be returned. There are currently three aggregation methods for all data points within the selected area: "average" takes the average value, "closest" the data point with the smallest distance to the camera and "weighted" creates the weighted average using the confidence data provided by each API. Note that phyphox automatically drops the lowest confidence value and that lower confidences typically only appear at edges and represent a small portion of most scenes. Therefore, the difference between "average" and "weighted" should be negligible for most situations.
 +
 +
In order to give the user a preview and control over the depth input, you will want to also add a depth-gui view element to the configuration (see in the views section).
 +
 +
;mode
 +
: Defines the aggregation method and can be "average", "closest" or "weighted" (see description above).
 +
: ''optional'', default: closest
 +
;x1, x2, y1, y2
 +
: Sets the initial acquisition area, which can still be modified by the user. x1 and x2 describe the horizontal limits and y1 and y2 the vertical ones. The values are floating point values ranging from 0.0 to 1.0, with 0.0 refering to the left/top edge of the image and 1.0 to the right/bottom edge.
 +
: ''optional'', default: 0.4, 0.6, 0.4, 0.6
 +
;smooth
 +
: Only applies to LiDAR on iOS devices. Can be set to true or false, to use smoothedSceneDepth (https://developer.apple.com/documentation/arkit/arframe/3674209-smoothedscenedepth) or sceneDepth (https://developer.apple.com/documentation/arkit/arframe/3566299-scenedepth), employing ARkits smoothing or not.
 +
: ''optional'', default: true
 +
 +
=== Input module: location ===
 +
 +
'''Available since phyphox file format 1.5 (phyphox 1.0.7)'''
 +
 +
<nowiki>
 +
<location>
 +
    <output component="x">BUFFER</output>
 +
    ...
 +
    <output component="t">BUFFER</output>
 +
</location>
 +
</nowiki>
 +
 +
The location block defines an input from the GPS sensor. The data will be written to the output buffers at the rate as it is provided from the sensor. On Android, the location data is expected to come from satellite navigation exclusively (although some unusual implementations may occur), but on iOS we cannot deactivate other sources. Therefore in most cases on iOS the first reading is based on the mobile and WIFI networks.
 +
 +
There are several components for the outputs:
 +
;t
 +
: Experiment time (seconds since start of experiment) for the location (as set by the operating system)
 +
;lat
 +
: Latitude in degree
 +
;lon
 +
: Longitude in degree
 +
;z
 +
: Elevation (note that elevation provided by GPS is generally rather imprecise) in meters (using EGM84 geoid as reference, i.e. "above see level")
 +
;zwgs84
 +
: Same as z but taking the WGS84 ellipsoid as reference (i.e. the coordinate system used by GPS). Note that the Android API provides WGS84 ellipsoid elevation while the iOS API provides EGM84 geoid elevation. Phyphox calculates the difference using a port of GeographiLib's algorithm with a 30' resolution EGM84 dataset (see https://geographiclib.sourceforge.io/).
 +
;v
 +
: Speed (provided by the system, based on consecutive GPS fixes) in m/s
 +
;dir
 +
: Direction (determined by the system along with the speed) in degree (counted from north towards east)
 +
;accuracy
 +
: An estimate by the system of the horizontal accuracy in meters
 +
;zAccuracy
 +
: An estimate by the system of the vertical accuracy in meters (not on Android)
 +
;satellites
 +
: Number of satellites used for this measurement (not on iOS)
 +
;status
 +
: -1 means that GPS is unavailable (usually deactivated by the user), 0 means that it is searching for a signal, 1 means that it is active. 2 means active, but the altitude is given above the WGS84 ellipsoid instead of the geoid, which can happen in the case of very basic GPS implementations on some (mostly cheap) phones. Note that this value is updated independently from the other outputs.
 +
 +
The location tag has no additional attributes.
  
 
=== Input module: sensor ===
 
=== Input module: sensor ===
  
 
  <nowiki>
 
  <nowiki>
−
<sensor type="TYPE" average="BOOLEAN" rate="FLOAT">
+
<sensor type="TYPE" average="BOOLEAN" rate="FLOAT" rateStrategy="STRATEGY" stride="INTEGER" ignoreUnavailable="BOOLEAN">
 
     <output component="x">BUFFER</output>
 
     <output component="x">BUFFER</output>
 
     ...
 
     ...
Line 231: Line 376:
 
</nowiki>
 
</nowiki>
  
−
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.
+
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. The exact strategy to achieve the target rate can be defined by the parameters ''rateStrategy'' and ''stride''. Please see details about this in the explanation of these parameters and note that these have been introduced with a behavior change in file format 1.14 (phyphox 1.1.10).
  
−
Note that 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.
+
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.
 
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
 
;type
 
: Defines the sensor type to be used. Allowed values:
 
: Defines the sensor type to be used. Allowed values:
 
:; accelerometer
 
:; accelerometer
−
:: The accelerometer in m/s². This gives the earth's acceleration when the device is resting.
+
:: 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
 
:; linear_acceleration
−
:: A virtual sensor giving the actual acceleration of the device. Should give zero when the device is resting.
+
:: 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)
 +
:; gravity
 +
:: A virtual sensor giving the gravitational acceleration in the frame of reference of the device. This removes the device motion from the accelerometer readings and should therefore be approximately the difference of accelerometer and linear_acceleration. (Depending on the implementation on each device.)  Available since file format 1.15 (phyphox 1.1.11)
 
:; magnetic_field
 
:; magnetic_field
 
:: Readings from the magnetometer in µT
 
:: Readings from the magnetometer in µT
 
:; gyroscope
 
:; gyroscope
 
:: Readings from the gyroscope in rad/s.
 
:: Readings from the gyroscope in rad/s.
 +
:; humidity
 +
:: Relative humidity in %. Available since file format 1.7 (phyphox 1.1.0)
 
:; light
 
:; light
 
:: The illuminance from the light sensor in lx
 
:: The illuminance from the light sensor in lx
 
:; pressure
 
:; pressure
 
:: The air pressure from the barometer in hPa
 
:: The air pressure from the barometer in hPa
 +
:; proximity
 +
:: Distance from the proximity sensor in cm (most devices only output 0cm or 5cm)
 +
:; temperature
 +
:: Temperature. This is supposed to be ambient temperature, but we have some fallback logic to find any temperature reading from the device. This usually represents the device temperature and cannot be used for external temperature measurement. (in °C) Available since file format 1.7 (phyphox 1.1.0)
 +
:; attitude
 +
:: The orientation (absolute rotation) of the device as calculated by the device's own algorithms. This uses TYPE_ROTATION_VECTOR on Android and "CMAttitude" from Core Motion on iOS, which (depending on the device) fuses data from the accelerometer, gyroscope and magnetometer to calculate the attitude of the device. The result is given as a quaternion in a reference system with y pointing towards magnetic North and z pointing upwards (the Android coordinate system, iOS attitude is converted to this system). The ''x'', ''y'' and ''z'' channels correspond to the last three components of the quaternion (w, x, y, z) and w can be retrieved through the ''abs'' channel. Available since file format 1.9 (phyphox 1.1.5)
 +
:; custom
 +
:: Use typeFilter and/or nameFilter to use a sensor that is not directly supported by phyphox. You can check the device info (i menu on main screen) to see which sensors are available on your phone. Phyphox will pick the first sensor with a type that matches the typeFilter (if set) and a name that contains the value of nameFilter (not case-sensitive, only if set). Note, that not all sensors will work properly with phyphox, especially if they do not generate values but events or states. Available since file format 1.19 (phyphox 1.2.0)
 
: ''required''
 
: ''required''
 
;rate
 
;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.
+
: 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 that can be achieved.
 
: ''optional'', default: 0.0
 
: ''optional'', default: 0.0
 
;average
 
;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.
 
: 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
 
: ''optional'', default: false
−
 
+
;rateStrategy
−
=== Input module: audio ===
+
: Defines the strategy to achieve the rate set with the attribute ''rate''. Available since file format 1.14 (phyphox 1.1.10)
−
 
+
:; auto
−
<nowiki>
+
:: Requests the target sensor rate directly from the system like the strategy ''request''. If the actual rate provided by the system is more than 10% faster than the requested rate, the strategy automatically switches to ''generate'', delivering the data points exactly at the desired rate. This is strategy prevents duplicate data points as both strategies cannot be faster than what the sensor provides and it picks the ideal method to achieve get close to the target rate. However, in cases when it has to switch to ''generate'' it is susceptible to strong sampling effects when the target rate is close to the actual sensor rate.
−
<audio rate="INTEGER">
+
:; request
−
    <output>BUFFER</output>
+
:: The target rate set by ''rate'' is directly requested from the system and the provided sensor data will be provided as is. It depends on the system if the provided rate is close to the requested one and the system might not be able to provide sensor data at given rates or it might decide to provide a different rate if the sensor data is shared with other apps. This strategy is most likely to yield a rate that strongly differs from the expected one, but as it will not group or discard data points, it will not introduce additional sampling or aliasing effects. For the same reason, the ''average'' attribute has no effect.
−
</audio>
+
:; generate
−
</nowiki>
+
:: The target rate is generated internally by phyphox while requesting the highest possible rate from the system. It is guaranteed to give data points at the rate set by ''rate'' and can even exceed the sensor rate (be careful not to waste performance with this). While the resulting data points seem very easy to interpret afterwards and while it makes it easy to synchronize different sensors, this strategy can severely degrade the recorded sensor data as data points might be duplicated or discarded in unforeseen patterns. If the target rate is close to the actual internal sensor rate, this will very likely introduce additional sampling effects like aliasing between the sensors sample rate and this target rate. Therefore, this strategy is recommended for educational purposes to simplify data analysis, but if you know how to analyze data and want the best possible data quality, it is highly recommended to use the ''request'' strategy instead as you can emulate the ''generate'' strategy in your data analysis later, but you could not go back to the quality of ''request'' from ''generate'' data.
−
 
+
:; limit
−
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 maximum sensor rate is requested by the system and the setting of ''rate'' is used as a limiter. More precisely, phyphox generates a new data point whenever the time interval from the last data point to the latest sensor event exceeds 1/''rate''. The resulting rate will always be close to but lower than the requested rate and the actual rate strongly depends on the actual sensor rate. This strategy is a compromise to get close to a target rate without the strong degradation introduced by the ''generate'' strategy as it usually leads to a similar number of sensor events per actually generated data points. The downside is that the data point rate may be quite different on different devices if the target rate is in the range of typical sensor rates. Note that this was the only rate strategy before file format 1.14 (phyphox 1.1.10) and that this is the default behavior if your phyphox-file targets a file format before 1.14.
−
 
+
: ''optional'', default: "auto" (Note, that experiment configurations with a file format below 1.14 will default to "limit" to assure backwards compatibility with the old behavior)
−
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.
+
; stride
−
 
+
: If stride is set to N, only every Nth data point generated by the ''rateStrategy'' (see above) is used. Other data points are simply discarded. A stride of 1 will use every data point, a stride of 2 only every second, a stride of 3 only every third and so on. This is mostly useful to achieve a very specific data rate on a specific device that is a integer fraction of the actual sensor rate in order to avoid additional aliasing effects from non-fractional rates. Available since file format 1.14 (phyphox 1.1.10)
−
;rate
+
: ''optional'', default: "1" (use every data point)
−
: The recording rate in Hz.
+
;ignoreUnavailable
−
: ''optional'', default: 48000
+
: Allow the user to open and start the experiment even if the sensor is not available. You won't receive any data for that server if it is not available and your experiment should still work and make sense for the user if this is the case. Available since file format 1.8 (phyphox 1.1.3)
−
 
+
;typeFilter
 +
:  See custom sensor type. Available since file format 1.19 (phyphox 1.2.0)
 +
: ''optional'', default: not set
 +
;nameFilter
 +
: See custom sensor type. Available since file format 1.19 (phyphox 1.2.0)
 +
: ''optional'', default: not set
  
 
== Block: output ==
 
== Block: output ==
Line 295: Line 463:
  
 
  <nowiki>
 
  <nowiki>
−
<audio rate="INTEGER" loop="BOOLEAN">
+
<audio rate="INTEGER" loop="BOOLEAN" normalize="BOOLEAN">
 
     <input>BUFFER</input>
 
     <input>BUFFER</input>
 +
    <tone>
 +
        <input parameter="amplitude" type="VALUE/BUFFER">VALUE/BUFFER</input>
 +
        <input parameter="frequency" type="VALUE/BUFFER">VALUE/BUFFER</input>
 +
        <input parameter="duration" type="VALUE/BUFFER">VALUE/BUFFER</input>
 +
    </tone>
 +
    <tone>
 +
        <input parameter="amplitude" type="VALUE/BUFFER">VALUE/BUFFER</input>
 +
        <input parameter="frequency" type="VALUE/BUFFER">VALUE/BUFFER</input>
 +
        <input parameter="duration" type="VALUE/BUFFER">VALUE/BUFFER</input>
 +
    </tone>
 +
    <noise>
 +
        <input parameter="amplitude" type="VALUE/BUFFER">VALUE/BUFFER</input>
 +
        <input parameter="duration" type="VALUE/BUFFER">VALUE/BUFFER</input>
 +
    </noise>
 
</audio>
 
</audio>
 
</nowiki>
 
</nowiki>
  
−
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.
+
The audio tag defines audio as an output (i.e. a speaker). The audio waveform can be composed from one or multiple sources:
 +
 
 +
'''input'''
 +
An input tag on the immediate level below ''audio'' denotes a direct source. 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. It has a fixed amplitude of 1 and the duration is defined by the number of samples in the input buffer. Audio data is represented by values ranging from -1 to +1. Only one direct source is supported.
  
−
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.
+
'''tone'''
 +
A '''tone''' block represents a parametric tone generator. Its parameters '''amplitude''', '''duration''' and '''frequency''' can either be fixed values (type="value") or a buffer (type="buffer", default) to control it dynamically. Each tone block (multiple are allowed) generates a sine tone and keeps track of the momentary phase of the sine function to avoid click noises due to mismatch of the frequency and the sampling rate or when changing the frequency. '''Available since file format 1.10 (phyphox version [[Version_history#1.1.6|version 1.1.6]]).'''
  
−
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.
+
'''noise'''
 +
A '''noise''' block represents a generator for white noise. Its parameters '''amplitude''' and '''duration''' can either be fixed values (type="value") or a buffer (type="buffer", default) to control it dynamically. Only one ''noise'' block is supported. '''Available since file format 1.10 (phyphox version [[Version_history#1.1.6|version 1.1.6]]).'''
 +
 
 +
Playback is triggered after each analysis process and each source can have individual durations (in seconds) and amplitudes (float value with 0.0 being silent and 1.0 maximum amplitude without clipping). If loop is set to true, the playback will loop. 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
 
;rate
 
: The recording rate in Hz.
 
: The recording rate in Hz.
 
: ''optional'', default: 48000
 
: ''optional'', default: 48000
 +
;loop
 +
: Loop playback
 +
: ''optional'', default: false
 +
; normalize
 +
: Normalize the amplitude of all inputs to achieve a total amplitude of 1. If the sum of all inputs exceeds 1 and this options is disabled, distortions might occur as the momentary amplitude might exceed 1 and get truncated. '''Available since file format 1.10 (phyphox version [[Version_history#1.1.6|version 1.1.6]]).'''
 +
: ''optional'', default: false
 +
 +
=== Output module: bluetooth ===
 +
 +
'''Available since phyphox file format 1.7 (phyphox 1.1.0)'''
 +
 +
The bluetooth block defines an output to a Bluetooth Low Energy device. Please refer to the documentation on the [[Bluetooth Low Energy]] interface in phyphox for details.
  
 
== Block: analysis ==
 
== Block: analysis ==
Line 314: Line 515:
 
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.
 
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'' and/or ''onUserInput'' to pause the analysis loop.
+
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
 
;sleep
 
: The minimum time in seconds before the whole analysis block is executed again after the last execution has finished. Decimal values allowed.
 
: 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)
 
: ''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: not set (no dynamic sleep)
 
;onUserInput
 
;onUserInput
 
: If true, the analysis block will not be executed again unless the user changes the content of an input view.
 
: If true, the analysis block will not be executed again unless the user changes the content of an input view.
 
: ''optional'', default: 'false'
 
: ''optional'', default: 'false'
 +
;requireFill
 +
: Sets the name of a data container that needs to be filled. The attribute requireFillThreshold or requireFillDynamic define a required number of elements in the data container (default 1 element). If this number is not fulfilled, the analysis block is skipped. '''Available since phyphox file format 1.16 ([[Version_history#1.1.12|phyphox 1.1.12]])'''
 +
;requireFillThreshold
 +
: A static integer number setting the threshold for the requireFill attribute. '''Available since phyphox file format 1.16 ([[Version_history#1.1.12|phyphox 1.1.12]])'''
 +
: ''optional'', default: '1'
 +
;requireFillDynamic
 +
: A dynamic value for the required number of elements in the data container defined by requireFill. This attribute points to another data container, which defines this value. If it is empty, the value from requireFillThreshold is used instead. '''Available since phyphox file format 1.16 ([[Version_history#1.1.12|phyphox 1.1.12]])'''
 +
: ''optional'', default: '' (requireFillThreshold used instead)
 +
;timedRun
 +
: Enable the timed run setting by default. This just acts as a preset. The user can still deactivate it from the main menu. '''Available since phyphox file format 1.10 ([[Version_history#1.1.6|phyphox 1.1.6]])'''
 +
: ''optional'', default: 'false' (deactivated)
 +
;timedRunStartDelay
 +
: Start delay in seconds for the timed run setting. This just acts as a preset. The user can still change it from the main menu. Also, this does not enable the function by default. To enable it, see ''timedRun'' above. '''Available since phyphox file format 1.10 ([[Version_history#1.1.6|phyphox 1.1.6]])'''
 +
: ''optional'', default: '3'
 +
;timedRunStopDelay
 +
: Stop delay in seconds for the timed run setting. This just acts as a preset. The user can still change it from the main menu. Also, this does not enable the function by default. To enable it, see ''timedRun'' above. '''Available since phyphox file format 1.10 ([[Version_history#1.1.6|phyphox 1.1.6]])'''
 +
: ''optional'', default: '10'
 +
;optimization
 +
: '''Removed in phyphox file format 1.10 (phyphox 1.1.6)''' This barely added any value but increased confusion significantly.
  
 
  <nowiki>
 
  <nowiki>
 
<phyphox version="1.0">
 
<phyphox version="1.0">
 
     ...
 
     ...
−
     <analysis sleep="2.0" onUserInput="false">
+
     <analysis sleep="2.0" dynamicSleep="buffer" onUserInput="false">
 
         <add>
 
         <add>
 
             <input>Buffer1</input>
 
             <input>Buffer1</input>
Line 335: Line 558:
 
             <input type="value" as="dividend">1</input>
 
             <input type="value" as="dividend">1</input>
 
             <input as="divisor">sumBuffer</input>
 
             <input as="divisor">sumBuffer</input>
−
             </output>inverseSum</output>
+
             <output>inverseSum</output>
 
         </divide>
 
         </divide>
 
     </analysis>
 
     </analysis>
Line 349: Line 572:
 
</nowiki>
 
</nowiki>
  
−
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.
+
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 omited 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.
+
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.
 
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.
+
'''Since file format version 1.10 (phyphox 1.1.6)''' all analysis module support a new attribute that allows to determine whether the module should be executed in each anlysis cycle or only for specific cycles. For this, each run of the analysis process (a cycle) is numbered. When the user opens the experiment and '''before''' he presses start, analysis is triggered with the cycle number 0, which can be used to prepare some buffers or fill graphs with defaults. After pressing start, the first cycle is number 1, followed by cycle 2 etc.
 +
 
 +
You can then set the attribute ''cycles'' for any analysis module. If not set, the module is executed in every cycle (including 0). If set it is only executed in the cycles that you specify by a space separated list. For example, cycles="1 3 42" means that the module is only executed in cycle 1, 3 and 42. You can also define ranges with a simple dash, so cycles="3-6" means that it will be executed in 3, 4, 5 and 6. Open ended lists can be achieved by simply omitting a number, so cycles="1-" will run in every cycle except for 0 and cycles="-5" will run in every cycle up to and including number 5. As a final example, mixing all these, cycles="0 3 5-7 10-" will run in cycle 0, 3, 5, 6, 7, 10 and then every subsequent cycle.
 +
 
 +
;attributes
 +
: for all analysis modules
 +
:; cycles
 +
:: Determine in which cycles the modules should be executed, see above. default: Execute in every cycle.
  
 
;input-tag
 
;input-tag
Line 365: Line 595:
 
::  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
 
::  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''
 
::  ''optional'', default: ''buffer''
 +
:; keep
 +
::  ''true'' 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: ''false''
 +
:; clear (deprecated in file format 1.17)
 +
::  ''false'' will mean, that the buffer retains its data after reading. If set to true, the buffer is cleared after reading, which can be used to process each dataset from an input only once. Note that this attribute has been deprecated with file format 1.17 (phyphox 1.1.13) and should be repalced with the more intuitive keep attribute. clear=true corresponds to keep=false.
 +
::  ''optional'', default: ''true''
  
 
;output-tag
 
;output-tag
Line 371: Line 607:
 
::  The mapping of the input to a function
 
::  The mapping of the input to a function
 
::  ''optional'' or ''required'' depending on the module
 
::  ''optional'' or ''required'' depending on the module
 +
:; append
 +
::  ''true'' will mean, that new data is appended to the content that is already in the buffer. ''false'' will clear the buffer first, effectively replacing its content with new data.
 +
::  ''optional'', default: ''false''
 +
:; clear (deprecated in file format 1.17)
 +
::  ''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. Note that this attribute has been deprecated with file format 1.17 (phyphox 1.1.13) and should be repalced with the more intuitive append attribute. clear=true corresponds to append=false.
 +
::  ''optional'', default: ''true''
  
−
=== Analysis module: add ===
+
=== List of analysis modules ===
−
 
 
−
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: 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.
 
−
 
 
−
;''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.
 
−
 
 
−
;''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.
 
−
 
 
−
;''value''
 
−
: ''input''
 
−
: ''as'' not required
 
−
: Number of inputs: Exactly one
 
−
 
 
−
;''tan''
 
−
: ''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: 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.
 
−
 
 
−
This module will return exactly one value per call.
 
−
 
 
−
;''x''
 
−
: ''input''
 
−
: ''as'' required
 
−
: Number of inputs: One or none
 
−
;''y''
 
−
: ''input''
 
−
: ''as'' required
 
−
: Number of inputs: Exactly one
 
−
 
 
−
;''max''
 
−
: ''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
 
−
: 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.
+
The specific mappings, attributes and functionality of the analysis modules are documented on a separate page listing all the [[analysis modules]].
−
 
 
−
;''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: 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: 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".
 
−
 
 
−
<nowiki>
 
−
<rangefilter>
 
−
    <input>in1</input>
 
−
    <input as="min" type="value">0</max>
 
−
    <input as="max" type="value">42</max>
 
−
    <input>in2</input>
 
−
    <input>in3</input>
 
−
    <input as="max">limit</max>
 
−
    <output>out1</output>
 
−
    <output>out2</output>
 
−
    <output>out3</output>
 
−
</rangefilter>
 
−
</nowiki>
 
−
 
 
−
;''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: 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
 
  
 
== Block: views ==
 
== Block: views ==
Line 837: Line 659:
  
 
<code>
 
<code>
−
<info label="INFOTEXT" labelsize="FLOAT" />
+
<info color="COLOR" label="INFOTEXT" bold="BOOLEAN" italic="BOOLEAN" align="STRING" size="NUMERIC" />
 
</code>
 
</code>
  
Line 845: Line 667:
 
: The text to be displayed to the user
 
: The text to be displayed to the user
 
: ''required''
 
: ''required''
−
;labelSize
+
;color
−
: The size of the label as a factor of the default size.
+
: The text color as six-digit RGB hex value or a named choice from the phyphox [[Colors]]
−
: ''optional'', default: 1.0
+
: ''optional'', default: white, '''Available since phyphox file format 1.7 (phyphox 1.1.0)'''
 +
;bold
 +
:If set to true, the text will be displayed using a bold font. (We cannot guarantee, that the combination of bold and italic is available on every device.) '''Available since phyphox file format 1.8 (phyphox 1.1.3)'''
 +
;italic
 +
:If set to true, the text will be displayed using an italic font. (We cannot guarantee, that the combination of bold and italic is available on every device.) '''Available since phyphox file format 1.8 (phyphox 1.1.3)'''
 +
;align
 +
:Can be set to left (default), center or right. The alignment of the text. (Note, that phyphox does not yet support RTL languages, but this attribute is designed to be reverse in such cases.) '''Available since phyphox file format 1.8 (phyphox 1.1.3)'''
 +
;size
 +
:Sets the font size of the info element as a factor to the default size. Hence, the default is 1. '''Available since phyphox file format 1.8 (phyphox 1.1.3)'''
 +
 
 +
=== View-Element: separator ===
 +
 
 +
<code>
 +
<separator color="orange" height="0.1" />
 +
</code>
  
 +
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 or a named color from the phyphox [[Colors]]) 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 or a named choice from the phyphox [[Colors]]
 +
: ''optional'', default: background color
 +
;height
 +
: The height of the separator in text line heights
 +
: ''optional'', default: 0.1
  
 
=== View-Element: value ===
 
=== View-Element: value ===
  
 
  <nowiki>
 
  <nowiki>
−
<value label="LABEL" labelsize="FLOAT" precision="INTEGER" scientific="BOOLEAN" unit="UNIT" factor="FLOAT">
+
<value label="LABEL" size="FLOAT" precision="INTEGER" scientific="BOOLEAN" unit="UNIT" factor="FLOAT" color="COLOR">
 
     <input>BUFFER</input>
 
     <input>BUFFER</input>
 +
    <map min="DOUBLE" max="DOUBLE">STRING</map>
 +
    <map>STRING</map>
 
</value>
 
</value>
 
</nowiki>
 
</nowiki>
  
 
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).
 
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
 
;label
 
: A label for this element
 
: A label for this element
 
: ''required''
 
: ''required''
−
;labelSize
+
;color
−
: The size of the label as a factor of the default size.
+
: The text color as six-digit RGB hex value or a named choice from the phyphox [[Colors]]
−
: ''optional'', default: 1.0
+
: ''optional'', default: white, '''Available since phyphox file format 1.7 (phyphox 1.1.0)'''
 +
;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
 
;precision
 
: The number of digits after the decimal point.
 
: The number of digits after the decimal point.
Line 883: Line 733:
  
 
  <nowiki>
 
  <nowiki>
−
<graph label="LABEL" labelsize="FLOAT" aspectRatio="FLOAT" style="STYLE" partialUpdate="BOOLEAN" forceFullDataset="BOOLEAN" history="INTEGER" labelX="LABELX" labelY="LABELY" logX="BOOLEAN" logy="BOOLEAN">
+
<graph label="LABEL" aspectRatio="FLOAT" style="STYLE" partialUpdate="BOOLEAN" labelX="LABELX" labelY="LABELY" timeOnX="BOOLEAN" timeOnY="BOOLEAN" linearTime="BOOLEAN" systemTime="BOOLEAN" hideTimeMarkers="BOOLEAN" logX="BOOLEAN" logy="BOOLEAN" xPrecision="INTEGER" yPrecision="INTEGER" minX="0" maxX="0" minY="0" maxY="0" scaleMinX="auto" scaleMaxX="auto" scaleMinY="auto" scaleMaxY="auto" followX="false" lineWidth="1" color="orange">
 
     <input axis="x">XBUFFER</input>
 
     <input axis="x">XBUFFER</input>
 
     <input axis="y">YBUFFER</input>
 
     <input axis="y">YBUFFER</input>
−
</value>
+
</graph>
 
</nowiki>
 
</nowiki>
  
−
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 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''. See below for additional option for other graph types.
  
−
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.
+
The resulting graph can be made up of lines (default) or dots (set attribute ''style'' to ''dots''). (see attribute descriptions below)
  
−
The attributes ''partialUpdate'' and ''forceFullDataset'' are used for performance optimization. ''PartialUpdate'' is used 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. ''forceFullDataset'' on the other hand disables a display optimization of the graph. The default behaviour is that if the multiple data points would be displayed on the same display x-coordinate (same pixel on the x-axis), they are averaged and then displayed. If this is not desirable (for example because extrema get washed out), this function can be disabled by setting "forceFullDataset" to true, which will draw every single value. Note, that this may be quite a parformance hit for large datasets on old devices.
+
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
 
;label
 
: A label for this element
 
: A label for this element
 
: ''required''
 
: ''required''
−
;labelSize
 
−
: The size of the label as a factor of the default size.
 
−
: ''optional'', default: 1.0
 
 
;apectRatio
 
;apectRatio
 
: The ratio of the total width of this element to the total height of this element in the view. (Including labels and axes)
 
: 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
 
: ''optional'', default: 3
 
;style
 
;style
−
: If set to ''dots'', the graph will not connect the values with lines.
+
: 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).
 
: ''optional'', default: display lines
 
: ''optional'', default: display lines
 
;partialUpdate
 
;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.
 
: 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
 
: ''optional'', default: false
−
;forceFullDataset
 
−
: If set to true, an optimization is enabled, which averages all data points that would end on the same x-axis pixel coordinate.
 
−
: ''optional'', default: false (= optimization enabled)
 
−
;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.
 
−
: ''optional'', default: 1
 
 
;labelX
 
;labelX
 
: The label of the x axis
 
: The label of the x axis
−
: ''optional'', default: empty, but you should always label your axes...
+
: ''optional'', default: empty, but you should always label your axes... (Note that since file format 1.7 (phyphox 1.1.0) you should set the unit separately in the attribute unitX)
 
;labelY
 
;labelY
 
: The label of the y axis
 
: The label of the y axis
−
: ''optional'', default: empty, but you should always label your axes...
+
: ''optional'', default: empty, but you should always label your axes... (Note that since file format 1.7 (phyphox 1.1.0) you should set the unit separately in the attribute unitY)
 +
;unitX
 +
: The unit of the x axis
 +
: ''optional'', default: empty, the units will be appended to the label, but are also used to give values of individual data points with correct units '''Available since phyphox file format 1.7 (phyphox 1.1.0)'''
 +
;unitY
 +
: The unit of the y axis
 +
: ''optional'', default: empty, the units will be appended to the label, but are also used to give values of individual data points with correct units '''Available since phyphox file format 1.7 (phyphox 1.1.0)'''
 +
;unitYperX
 +
: An explicit unit for slopes, if not set, phyphox will use "unitY / unitX".
 +
: ''optional'', default: not set, phyphox will fallback to generate this from x and y unit. '''Available since phyphox file format 1.10 (phyphox 1.1.6)'''
 +
;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 to mark start/pause events and to switch to a system time scale (i.e. absolute date and time) on the x axis. '''Available since phyphox file format 1.12 (phyphox 1.1.8)'''
 +
: ''optional'', 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 to mark start/pause events and to switch to a system time scale (i.e. absolute date and time) on the y axis. '''Available since phyphox file format 1.12 (phyphox 1.1.8)'''
 +
: ''optional'', 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 to plot 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. '''Available since phyphox file format 1.12 (phyphox 1.1.8)'''
 +
: ''optional'', default: false
 +
;systemTime
 +
: If set to true, time axes will start as a system time scale (they can always be switched by the user). '''Available since phyphox file format 1.12 (phyphox 1.1.8)'''
 +
: ''optional'', default: false
 +
;hideTimeMarkers
 +
: If set to true, no red markers are shown to indicate times at which the experiment was stopped. '''Available since phyphox file format 1.14 (phyphox 1.1.10)'''
 +
: ''optional'', default: false (= markers are visible)
 
;logX
 
;logX
 
: If set to true, the x axis will be on a logarithmic scale
 
: If set to true, the x axis will be on a logarithmic scale
Line 928: Line 793:
 
: If set to true, the y axis will be on a logarithmic scale
 
: If set to true, the y axis will be on a logarithmic scale
 
: ''optional'', default: false
 
: ''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
 +
;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. '''Available since phyphox file format 1.19 (phyphox 1.2.0)'''
 +
: ''optional'', default: false
 +
;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
 +
;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. '''Available since phyphox file format 1.15 (phyphox 1.1.11)'''
 +
: ''optional'', default: false
 +
;lineWidth
 +
: Width of the graph line relative to the default width
 +
: ''optional'', default: 1
 +
;color
 +
: Color of the graph line as six-digit RGB hex value or a named choice from the phyphox [[Colors]]
 +
: ''optional'', default: phyphox orange
 +
;history
 +
: '''Deprecation warning''': This feature has been marked as depricated 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))'''
 +
: ''optional'', default: 1
 +
 +
====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 similar to the traditional 2D plots:
 +
 +
<nowiki>
 +
<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>
 +
</nowiki>
 +
 +
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 needs to have exactly the same value, so the value has to be provide for every single data point. However, you cannot just provide arbitrarily distributed data point.
 +
 +
The color map creates a lattice from the provided points, which is then colored. For this, an additional paramtere "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 connection to the next row won't match up. If you need to plot random data pairs, you might want to check our the [[Analysis_modules#map|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 monotonous instead of the x axis.
 +
 +
The color map plot introduces the following additional attributes:
 +
 +
;labelZ
 +
: The label of the z axis
 +
: ''optional'', default: empty, but you should always label your axes...
 +
;logZ
 +
: If set to true, the x axis will be on a logarithmic scale
 +
: ''optional'', default: false
 +
;zPrecision
 +
: The number of significant digits on the z axis.
 +
: ''optional'', default: 3
 +
;minZ
 +
: Lowest value on the z axis. Only applied if scaleMinZ = fixed
 +
: ''optional'', default: 0
 +
;maxZ
 +
: Highest value on the z axis. Only applied if scaleMaxZ = fixed
 +
: ''optional'', default: 0
 +
;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'', 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 minimum to maxZ.
 +
: ''optional'', default: auto
 +
;mapWidth
 +
: Number of data points per line.
 +
: ''optional'', but a color map chart won't work without this.
 +
;mapColor[n]
 +
: n-th color in the color map
 +
: ''optional'', if none are defined, phyphox uses a black-orange-white color gradient
 +
 +
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 a simply defined as a series of colors that are spread across the z range:
 +
 +
<nowiki>
 +
<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>
 +
</nowiki>
 +
 +
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:
 +
 +
<nowiki>
 +
<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>
 +
</nowiki>
 +
 +
This example just creates four line charts for the "multi" page of the raw accelerometer experiment. You can define different colors (color attribute), line widths (lineWidth) and plot styles (style as line, dots, vbars or hbars) by applying these attributes to the input tag instead of the graph tag. Here, it does not matter if you define these for the x or y axis, but you should make sure that all inputs are assigned to an axis and that they are ordered correctly.
  
 
=== View-Element: edit ===
 
=== View-Element: edit ===
  
 
  <nowiki>
 
  <nowiki>
−
<edit label="LABEL" labelsize="FLOAT" signed="BOOLEAN" decimal="BOOLEAN" unit="UNIT" factor="FLOAT" default="FLOAT">
+
<edit label="LABEL" signed="BOOLEAN" decimal="BOOLEAN" min="FLOAT" max="FLOAT" unit="UNIT" factor="FLOAT" default="FLOAT">
 
     <output>BUFFER</output>
 
     <output>BUFFER</output>
 
</value>
 
</value>
Line 942: Line 942:
 
: A label for this element
 
: A label for this element
 
: ''required''
 
: ''required''
−
;labelSize
 
−
: The size of the label as a factor of the default size.
 
−
: ''optional'', default: 1.0
 
 
;signed
 
;signed
 
: If set to ''false'' the user may not enter negative numbers.
 
: If set to ''false'' the user may not enter negative numbers.
Line 951: Line 948:
 
: If set to ''false'' the user may not enter decimal (i.e. non-integer) numbers.
 
: If set to ''false'' the user may not enter decimal (i.e. non-integer) numbers.
 
: ''optional'', default: true
 
: ''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
 
;unit
 
: A unit to be displayed after the value
 
: A unit to be displayed after the value
Line 956: Line 959:
 
;factor
 
;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
 
: 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
+
: ''optional'', default: 1.0
 
;default
 
;default
 
: The default value of the edit box. The experiment will start with this value.
 
: The default value of the edit box. The experiment will start with this value.
 
: ''optional'', default: 0.0
 
: ''optional'', default: 0.0
 +
 +
=== View-Element: button ===
 +
 +
'''Available since phyphox file format 1.3 (phyphox 1.0.4)'''
 +
 +
<nowiki>
 +
<button label="LABEL">
 +
    <input>BUFFER1</input>
 +
    <output>BUFFER1</output>
 +
    <input type="value">42</input>
 +
    <output>BUFFER2</output>
 +
    <input type="empty" />
 +
    <output>BUFFER3</output>
 +
    <trigger>ID</trigger>
 +
</button>
 +
</nowiki>
 +
 +
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.
 +
 +
Since version 1.8 (phyphox 1.1.3) in addition to defining in and out buffer (or usually as an alternative), you can set a trigger tag defining an id. This triggers matching processes with the same id like a [[Network Connections|network connection]] (the only example at the time of this writing).
 +
 +
;label
 +
: A label for this element
 +
: ''required''
 +
 +
 +
=== View-Element: depth-gui ===
 +
 +
'''Available since phyphox file format 1.14 (phyphox 1.1.10)'''
 +
 +
<nowiki>
 +
<depth-gui label="LABEL" />
 +
</nowiki>
 +
 +
This is a preview and control for a depth input, showing a preview of the camera and allowing for selecting an acquisition area, an aggregation method and switching cameras. At the moment, you can only set the label. Note that this only makes sense if you also use a depth input in the configuration.
 +
 +
=== View-Element: image ===
 +
 +
'''Available since phyphox file format 1.18 (phyphox 1.1.16)'''
 +
 +
<nowiki>
 +
    <image src="RESOURCE" scale="1.0" lightFilter="none" darkFilter="none" />
 +
</nowiki>
 +
 +
Display an image with the file name RESOURCE. Typically, RESOURCE is a png or jpg image (these are natively supported on both iOS and Android, hoping for SVG support on iOS eventually) that is placed in the resource folder "res" in a zip file along with the experiment XML file. So, for example, instead of sharing experiment.phyphox you would share a zip file that contains experiment.phyphox together with a folder called "res" that contains an image "demo.jpg". The image element would then set RESOURCE to "demo.jpg" (not res/demo.jpg), i.e. '''<image src="demo.jpg" />'''.
 +
 +
;src
 +
: The file name of the image that should be displayed. (Relative to the resource folder.)
 +
: ''required''
 +
;scale
 +
: Scales the size of the image. By default (scale="1.0") the image is shown in full width. The factor is relative to this, so scale="0.5" sets it to half the width of the view.
 +
: ''optional'', default: 1.0
 +
;lightFilter
 +
: A filter that should be applied to the image if the interface of phyphox is in light mode. Currently, there are two options: '''none''' leaves the image as is. '''invert''' inverts the colors of the image.
 +
: ''optional'', default: none
 +
;darkFilter
 +
: A filter that should be applied to the image if the interface of phyphox is in dark mode. Currently, there are two options: '''none''' leaves the image as is. '''invert''' inverts the colors of the image.
 +
: ''optional'', default: none
  
 
== Block: export ==
 
== Block: export ==
Line 988: Line 1,051:
 
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.
 
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 ===
+
'''Tag: data'''
  
 
  <nowiki>
 
  <nowiki>
Line 999: Line 1,062:
 
: A name describing the data
 
: A name describing the data
 
: ''required''
 
: ''required''
 +
 +
== Block: network ==
 +
 +
The network block can define network connections that allow requesting values from or sending data to a service on a network (local or internet). This function is documented on a [[Network Connections|separate page]].
 +
 +
== Block: events ==
 +
 +
The events block was introduced with file format 1.12 (phyphox version 1.1.8) as a temporary solution to store event and time reference data. It will be supported in the future to allow for reading old experiment state files, but at the time of this writing, there will be no specific use for this feature once the experiment state is stored in a form that separates measured data (and events) from the phyphox-configuration file.
 +
 +
The events block contains a list of event-block with tags corresponding to any known event, which are currently ''start'' and ''pause''. Each event needs to have an attribute ''experimentTime'' and an attribute ''systemTime'' giving the experiment time (seconds since first start, ignoring pauses) and the system time (milliseconds since 1970) of the event.
 +
 +
<nowiki>
 +
<phyphox version="1.0">
 +
    ...
 +
    <events>
 +
        <start experimentTime="0.0" systemTime="1608126693705"/>
 +
        <pause experimentTime="1.3307273210000001" systemTime="1608126695035"/>
 +
        <start experimentTime="1.3307273210000001" systemTime="1608126696552"/>
 +
        <pause experimentTime="2.310827263" systemTime="1608126697532"/>
 +
        ...
 +
    </events>
 +
    ...
 +
</phyphox>
 +
</nowiki>

Latest revision as of 13:46, 6 September 2024

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.

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: color

<color>COLOR</color>

The base color for the experiment. This is used as a background of the icon (if a text-based icon is used or if it has a transparent background) and for the label of the category. If a category contains experiments with different colors, the most common color is used.

Color can be defined as a 6-digit hex value or as one of the named Colors.

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" highlight="false">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). If the attribute highlight is set to true, the link will also be featured in the experiment menu. (Note, that the highlight attribute is meant to highlight especially relevant links, like instructions for the experiment. Its actual implementation, i.e. the way a link is "highlighted" might change in newer versions.)

Block: translations

The translations block may hold one or more translation (note: singular) blocks, describing the translations of strings shown to the user. Any string outside the translations block is considered to be in English and then translated to other languages from within the translations block, unless a different global language has been defined in the tag of the phyphox-block or if English appears explicitly as a translation block. If English is used in a translation block and no language has been defined in the phyphox-block, the text outside the translation block should be treated as a placeholder. 

<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: audio

<audio rate="INTEGER" append="false">
    <output>BUFFER</output>
    <output component="rate">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. Also, the rate you set is not guaranteed. Instead you should read the actual rate from the rate output (see example above) and use that for any calculations that use a time base. Note that the rate output is written independently from the recording output (mostly when the rate changes, which usually only should happen if the audio setup changes). Therefore you should not delete this buffer while reading it. The rate output is available since phyphox file format 1.6 (phyphox 1.0.10)

rate
The recording rate in Hz.
optional, default: 48000
append
Append data to the output buffer instead of only offering new data since the last analysis cycle. Available since file format 1.16 (phyphox version version 1.1.12).
optional, default: false (buffer contains only new data)

Input module: bluetooth

Available since phyphox file format 1.7 (phyphox 1.1.0)

The bluetooth block defines an input from a Bluetooth Low Energy device. Please refer to the documentation on the Bluetooth Low Energy interface in phyphox for details.


Input module: depth

Available since phyphox file format 1.14 (phyphox 1.1.10) 

<depth mode="AGGREGATIONMODE" x1="FLOAT" x2="FLOAT" y1="FLOAT" y2="FLOAT" smooth="BOOLEAN">
    <output component="z">BUFFER</output>
    <output component="t">BUFFER</output>
</depth>

Get a depth measurement from the depth sensor, which is typically a dedicated optical sesor as part of the camera array. On iOS, this type of sensor is called "LiDAR", while on Android you usually have to look for "ToF". Both systems have very different APIs to access this data with various advantages and drawbacks:

On iOS we access the LiDAR sensor through ARkit, which is the framework for augmented reality applications. The depth data is almost perfectly aligned with the camera image, but it is not raw data from the sensor, but processed and remapped for AR applications. Therefore, the data might have been fused with depth data derived from the normal color camera (for example depth estimation from parallax effects). Newer iOS devices also feature a depth sensor on the front, which is designed for FaceID, but this is available through an entirely different API and may be supported by phyphox in the future. (Details on Apple's API can be found at https://developer.apple.com/documentation/arkit/ardepthdata)

On Android we decided against using ARcore, Google's augmented reality framework, as a more direct API is available and dependencies on Google Services could be avoided in favor of platforms that do not have Google support. Here we use the camera2 API to access the sensor data, which has the benefit that we do not expect any fusion with AR data. However, the disadvantage is that the depth data has not been remapped to align with the regular camera image and you will experience an offset, which in particular will depend on the viewing distance as camera and sensor are placed at a distance in the phone's case. The camera2 API allows for accessing front and back facing depth sensors, but be aware that some phones advertise a ToF sensor for camera autofocus without exposing its data through the camera2 API. (Details on the camera2 API can be found at: https://developer.android.com/reference/android/hardware/camera2/package-summary)

Typically the user selects an area within the camera/depth data (which can be preset using the attributes x1, x2, y1, y2) that is aggregated into one depth value per frame. For each frame a pair of an aggregated depth value "z" and the corresponding timestamp "t" will be returned. There are currently three aggregation methods for all data points within the selected area: "average" takes the average value, "closest" the data point with the smallest distance to the camera and "weighted" creates the weighted average using the confidence data provided by each API. Note that phyphox automatically drops the lowest confidence value and that lower confidences typically only appear at edges and represent a small portion of most scenes. Therefore, the difference between "average" and "weighted" should be negligible for most situations.

In order to give the user a preview and control over the depth input, you will want to also add a depth-gui view element to the configuration (see in the views section).

mode
Defines the aggregation method and can be "average", "closest" or "weighted" (see description above).
optional, default: closest
x1, x2, y1, y2
Sets the initial acquisition area, which can still be modified by the user. x1 and x2 describe the horizontal limits and y1 and y2 the vertical ones. The values are floating point values ranging from 0.0 to 1.0, with 0.0 refering to the left/top edge of the image and 1.0 to the right/bottom edge.
optional, default: 0.4, 0.6, 0.4, 0.6
smooth
Only applies to LiDAR on iOS devices. Can be set to true or false, to use smoothedSceneDepth (https://developer.apple.com/documentation/arkit/arframe/3674209-smoothedscenedepth) or sceneDepth (https://developer.apple.com/documentation/arkit/arframe/3566299-scenedepth), employing ARkits smoothing or not.
optional, default: true

Input module: location

Available since phyphox file format 1.5 (phyphox 1.0.7) 

<location>
    <output component="x">BUFFER</output>
    ...
    <output component="t">BUFFER</output>
</location>

The location block defines an input from the GPS sensor. The data will be written to the output buffers at the rate as it is provided from the sensor. On Android, the location data is expected to come from satellite navigation exclusively (although some unusual implementations may occur), but on iOS we cannot deactivate other sources. Therefore in most cases on iOS the first reading is based on the mobile and WIFI networks.

There are several components for the outputs:

t
Experiment time (seconds since start of experiment) for the location (as set by the operating system)
lat
Latitude in degree
lon
Longitude in degree
z
Elevation (note that elevation provided by GPS is generally rather imprecise) in meters (using EGM84 geoid as reference, i.e. "above see level")
zwgs84
Same as z but taking the WGS84 ellipsoid as reference (i.e. the coordinate system used by GPS). Note that the Android API provides WGS84 ellipsoid elevation while the iOS API provides EGM84 geoid elevation. Phyphox calculates the difference using a port of GeographiLib's algorithm with a 30' resolution EGM84 dataset (see https://geographiclib.sourceforge.io/).
v
Speed (provided by the system, based on consecutive GPS fixes) in m/s
dir
Direction (determined by the system along with the speed) in degree (counted from north towards east)
accuracy
An estimate by the system of the horizontal accuracy in meters
zAccuracy
An estimate by the system of the vertical accuracy in meters (not on Android)
satellites
Number of satellites used for this measurement (not on iOS)
status
-1 means that GPS is unavailable (usually deactivated by the user), 0 means that it is searching for a signal, 1 means that it is active. 2 means active, but the altitude is given above the WGS84 ellipsoid instead of the geoid, which can happen in the case of very basic GPS implementations on some (mostly cheap) phones. Note that this value is updated independently from the other outputs.

The location tag has no additional attributes.

Input module: sensor

<sensor type="TYPE" average="BOOLEAN" rate="FLOAT" rateStrategy="STRATEGY" stride="INTEGER" ignoreUnavailable="BOOLEAN">
    <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. The exact strategy to achieve the target rate can be defined by the parameters rateStrategy and stride. Please see details about this in the explanation of these parameters and note that these have been introduced with a behavior change in file format 1.14 (phyphox 1.1.10).

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)
gravity
A virtual sensor giving the gravitational acceleration in the frame of reference of the device. This removes the device motion from the accelerometer readings and should therefore be approximately the difference of accelerometer and linear_acceleration. (Depending on the implementation on each device.) Available since file format 1.15 (phyphox 1.1.11)
magnetic_field
Readings from the magnetometer in µT
gyroscope
Readings from the gyroscope in rad/s.
humidity
Relative humidity in %. Available since file format 1.7 (phyphox 1.1.0)
light
The illuminance from the light sensor in lx
pressure
The air pressure from the barometer in hPa
proximity
Distance from the proximity sensor in cm (most devices only output 0cm or 5cm)
temperature
Temperature. This is supposed to be ambient temperature, but we have some fallback logic to find any temperature reading from the device. This usually represents the device temperature and cannot be used for external temperature measurement. (in °C) Available since file format 1.7 (phyphox 1.1.0)
attitude
The orientation (absolute rotation) of the device as calculated by the device's own algorithms. This uses TYPE_ROTATION_VECTOR on Android and "CMAttitude" from Core Motion on iOS, which (depending on the device) fuses data from the accelerometer, gyroscope and magnetometer to calculate the attitude of the device. The result is given as a quaternion in a reference system with y pointing towards magnetic North and z pointing upwards (the Android coordinate system, iOS attitude is converted to this system). The x, y and z channels correspond to the last three components of the quaternion (w, x, y, z) and w can be retrieved through the abs channel. Available since file format 1.9 (phyphox 1.1.5)
custom
Use typeFilter and/or nameFilter to use a sensor that is not directly supported by phyphox. You can check the device info (i menu on main screen) to see which sensors are available on your phone. Phyphox will pick the first sensor with a type that matches the typeFilter (if set) and a name that contains the value of nameFilter (not case-sensitive, only if set). Note, that not all sensors will work properly with phyphox, especially if they do not generate values but events or states. Available since file format 1.19 (phyphox 1.2.0)
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 that can be achieved.
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
rateStrategy
Defines the strategy to achieve the rate set with the attribute rate. Available since file format 1.14 (phyphox 1.1.10)
auto
Requests the target sensor rate directly from the system like the strategy request. If the actual rate provided by the system is more than 10% faster than the requested rate, the strategy automatically switches to generate, delivering the data points exactly at the desired rate. This is strategy prevents duplicate data points as both strategies cannot be faster than what the sensor provides and it picks the ideal method to achieve get close to the target rate. However, in cases when it has to switch to generate it is susceptible to strong sampling effects when the target rate is close to the actual sensor rate.
request
The target rate set by rate is directly requested from the system and the provided sensor data will be provided as is. It depends on the system if the provided rate is close to the requested one and the system might not be able to provide sensor data at given rates or it might decide to provide a different rate if the sensor data is shared with other apps. This strategy is most likely to yield a rate that strongly differs from the expected one, but as it will not group or discard data points, it will not introduce additional sampling or aliasing effects. For the same reason, the average attribute has no effect.
generate
The target rate is generated internally by phyphox while requesting the highest possible rate from the system. It is guaranteed to give data points at the rate set by rate and can even exceed the sensor rate (be careful not to waste performance with this). While the resulting data points seem very easy to interpret afterwards and while it makes it easy to synchronize different sensors, this strategy can severely degrade the recorded sensor data as data points might be duplicated or discarded in unforeseen patterns. If the target rate is close to the actual internal sensor rate, this will very likely introduce additional sampling effects like aliasing between the sensors sample rate and this target rate. Therefore, this strategy is recommended for educational purposes to simplify data analysis, but if you know how to analyze data and want the best possible data quality, it is highly recommended to use the request strategy instead as you can emulate the generate strategy in your data analysis later, but you could not go back to the quality of request from generate data.
limit
The maximum sensor rate is requested by the system and the setting of rate is used as a limiter. More precisely, phyphox generates a new data point whenever the time interval from the last data point to the latest sensor event exceeds 1/rate. The resulting rate will always be close to but lower than the requested rate and the actual rate strongly depends on the actual sensor rate. This strategy is a compromise to get close to a target rate without the strong degradation introduced by the generate strategy as it usually leads to a similar number of sensor events per actually generated data points. The downside is that the data point rate may be quite different on different devices if the target rate is in the range of typical sensor rates. Note that this was the only rate strategy before file format 1.14 (phyphox 1.1.10) and that this is the default behavior if your phyphox-file targets a file format before 1.14.
optional, default: "auto" (Note, that experiment configurations with a file format below 1.14 will default to "limit" to assure backwards compatibility with the old behavior)
stride
If stride is set to N, only every Nth data point generated by the rateStrategy (see above) is used. Other data points are simply discarded. A stride of 1 will use every data point, a stride of 2 only every second, a stride of 3 only every third and so on. This is mostly useful to achieve a very specific data rate on a specific device that is a integer fraction of the actual sensor rate in order to avoid additional aliasing effects from non-fractional rates. Available since file format 1.14 (phyphox 1.1.10)
optional, default: "1" (use every data point)
ignoreUnavailable
Allow the user to open and start the experiment even if the sensor is not available. You won't receive any data for that server if it is not available and your experiment should still work and make sense for the user if this is the case. Available since file format 1.8 (phyphox 1.1.3)
typeFilter
See custom sensor type. Available since file format 1.19 (phyphox 1.2.0)
optional, default: not set
nameFilter
See custom sensor type. Available since file format 1.19 (phyphox 1.2.0)
optional, default: not set

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" normalize="BOOLEAN">
    <input>BUFFER</input>
    <tone>
        <input parameter="amplitude" type="VALUE/BUFFER">VALUE/BUFFER</input>
        <input parameter="frequency" type="VALUE/BUFFER">VALUE/BUFFER</input>
        <input parameter="duration" type="VALUE/BUFFER">VALUE/BUFFER</input>
    </tone>
    <tone>
        <input parameter="amplitude" type="VALUE/BUFFER">VALUE/BUFFER</input>
        <input parameter="frequency" type="VALUE/BUFFER">VALUE/BUFFER</input>
        <input parameter="duration" type="VALUE/BUFFER">VALUE/BUFFER</input>
    </tone>
    <noise>
        <input parameter="amplitude" type="VALUE/BUFFER">VALUE/BUFFER</input>
        <input parameter="duration" type="VALUE/BUFFER">VALUE/BUFFER</input>
    </noise>
</audio>

The audio tag defines audio as an output (i.e. a speaker). The audio waveform can be composed from one or multiple sources:

input An input tag on the immediate level below audio denotes a direct source. 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. It has a fixed amplitude of 1 and the duration is defined by the number of samples in the input buffer. Audio data is represented by values ranging from -1 to +1. Only one direct source is supported.

tone A tone block represents a parametric tone generator. Its parameters amplitude, duration and frequency can either be fixed values (type="value") or a buffer (type="buffer", default) to control it dynamically. Each tone block (multiple are allowed) generates a sine tone and keeps track of the momentary phase of the sine function to avoid click noises due to mismatch of the frequency and the sampling rate or when changing the frequency. Available since file format 1.10 (phyphox version version 1.1.6).

noise A noise block represents a generator for white noise. Its parameters amplitude and duration can either be fixed values (type="value") or a buffer (type="buffer", default) to control it dynamically. Only one noise block is supported. Available since file format 1.10 (phyphox version version 1.1.6).

Playback is triggered after each analysis process and each source can have individual durations (in seconds) and amplitudes (float value with 0.0 being silent and 1.0 maximum amplitude without clipping). If loop is set to true, the playback will loop. 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
normalize
Normalize the amplitude of all inputs to achieve a total amplitude of 1. If the sum of all inputs exceeds 1 and this options is disabled, distortions might occur as the momentary amplitude might exceed 1 and get truncated. Available since file format 1.10 (phyphox version version 1.1.6).
optional, default: false

Output module: bluetooth

Available since phyphox file format 1.7 (phyphox 1.1.0)

The bluetooth block defines an output to a Bluetooth Low Energy device. Please refer to the documentation on the Bluetooth Low Energy interface in phyphox for details.

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: not set (no dynamic sleep)
onUserInput
If true, the analysis block will not be executed again unless the user changes the content of an input view.
optional, default: 'false'
requireFill
Sets the name of a data container that needs to be filled. The attribute requireFillThreshold or requireFillDynamic define a required number of elements in the data container (default 1 element). If this number is not fulfilled, the analysis block is skipped. Available since phyphox file format 1.16 (phyphox 1.1.12)
requireFillThreshold
A static integer number setting the threshold for the requireFill attribute. Available since phyphox file format 1.16 (phyphox 1.1.12)
optional, default: '1'
requireFillDynamic
A dynamic value for the required number of elements in the data container defined by requireFill. This attribute points to another data container, which defines this value. If it is empty, the value from requireFillThreshold is used instead. Available since phyphox file format 1.16 (phyphox 1.1.12)
optional, default: (requireFillThreshold used instead)
timedRun
Enable the timed run setting by default. This just acts as a preset. The user can still deactivate it from the main menu. Available since phyphox file format 1.10 (phyphox 1.1.6)
optional, default: 'false' (deactivated)
timedRunStartDelay
Start delay in seconds for the timed run setting. This just acts as a preset. The user can still change it from the main menu. Also, this does not enable the function by default. To enable it, see timedRun above. Available since phyphox file format 1.10 (phyphox 1.1.6)
optional, default: '3'
timedRunStopDelay
Stop delay in seconds for the timed run setting. This just acts as a preset. The user can still change it from the main menu. Also, this does not enable the function by default. To enable it, see timedRun above. Available since phyphox file format 1.10 (phyphox 1.1.6)
optional, default: '10'
optimization
Removed in phyphox file format 1.10 (phyphox 1.1.6) This barely added any value but increased confusion significantly.
<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.

Since file format version 1.10 (phyphox 1.1.6) all analysis module support a new attribute that allows to determine whether the module should be executed in each anlysis cycle or only for specific cycles. For this, each run of the analysis process (a cycle) is numbered. When the user opens the experiment and before he presses start, analysis is triggered with the cycle number 0, which can be used to prepare some buffers or fill graphs with defaults. After pressing start, the first cycle is number 1, followed by cycle 2 etc.

You can then set the attribute cycles for any analysis module. If not set, the module is executed in every cycle (including 0). If set it is only executed in the cycles that you specify by a space separated list. For example, cycles="1 3 42" means that the module is only executed in cycle 1, 3 and 42. You can also define ranges with a simple dash, so cycles="3-6" means that it will be executed in 3, 4, 5 and 6. Open ended lists can be achieved by simply omitting a number, so cycles="1-" will run in every cycle except for 0 and cycles="-5" will run in every cycle up to and including number 5. As a final example, mixing all these, cycles="0 3 5-7 10-" will run in cycle 0, 3, 5, 6, 7, 10 and then every subsequent cycle.

attributes
for all analysis modules
cycles
Determine in which cycles the modules should be executed, see above. default: Execute in every cycle.
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
keep
true 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: false
clear (deprecated in file format 1.17)
false will mean, that the buffer retains its data after reading. If set to true, the buffer is cleared after reading, which can be used to process each dataset from an input only once. Note that this attribute has been deprecated with file format 1.17 (phyphox 1.1.13) and should be repalced with the more intuitive keep attribute. clear=true corresponds to keep=false.
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
append
true will mean, that new data is appended to the content that is already in the buffer. false will clear the buffer first, effectively replacing its content with new data.
optional, default: false
clear (deprecated in file format 1.17)
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. Note that this attribute has been deprecated with file format 1.17 (phyphox 1.1.13) and should be repalced with the more intuitive append attribute. clear=true corresponds to append=false.
optional, default: true

List of analysis modules

The specific mappings, attributes and functionality of the analysis modules are documented on a separate page listing all the analysis modules.

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 color="COLOR" label="INFOTEXT" bold="BOOLEAN" italic="BOOLEAN" align="STRING" size="NUMERIC" />

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
color
The text color as six-digit RGB hex value or a named choice from the phyphox Colors
optional, default: white, Available since phyphox file format 1.7 (phyphox 1.1.0)
bold
If set to true, the text will be displayed using a bold font. (We cannot guarantee, that the combination of bold and italic is available on every device.) Available since phyphox file format 1.8 (phyphox 1.1.3)
italic
If set to true, the text will be displayed using an italic font. (We cannot guarantee, that the combination of bold and italic is available on every device.) Available since phyphox file format 1.8 (phyphox 1.1.3)
align
Can be set to left (default), center or right. The alignment of the text. (Note, that phyphox does not yet support RTL languages, but this attribute is designed to be reverse in such cases.) Available since phyphox file format 1.8 (phyphox 1.1.3)
size
Sets the font size of the info element as a factor to the default size. Hence, the default is 1. Available since phyphox file format 1.8 (phyphox 1.1.3)

View-Element: separator

<separator color="orange" 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 or a named color from the phyphox Colors) 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 or a named choice from the phyphox Colors
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" color="COLOR">
    <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
color
The text color as six-digit RGB hex value or a named choice from the phyphox Colors
optional, default: white, Available since phyphox file format 1.7 (phyphox 1.1.0)
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" labelX="LABELX" labelY="LABELY" timeOnX="BOOLEAN" timeOnY="BOOLEAN" linearTime="BOOLEAN" systemTime="BOOLEAN" hideTimeMarkers="BOOLEAN" logX="BOOLEAN" logy="BOOLEAN" xPrecision="INTEGER" yPrecision="INTEGER" minX="0" maxX="0" minY="0" maxY="0" scaleMinX="auto" scaleMaxX="auto" scaleMinY="auto" scaleMaxY="auto" followX="false" lineWidth="1" color="orange">
    <input axis="x">XBUFFER</input>
    <input axis="y">YBUFFER</input>
</graph>

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. See below for additional option for other graph types.

The resulting graph can be made up of lines (default) or dots (set attribute style to dots). (see attribute descriptions 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. See below for additional styles introduced with file format 1.7 (phyphox 1.1.0).
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
labelX
The label of the x axis
optional, default: empty, but you should always label your axes... (Note that since file format 1.7 (phyphox 1.1.0) you should set the unit separately in the attribute unitX)
labelY
The label of the y axis
optional, default: empty, but you should always label your axes... (Note that since file format 1.7 (phyphox 1.1.0) you should set the unit separately in the attribute unitY)
unitX
The unit of the x axis
optional, default: empty, the units will be appended to the label, but are also used to give values of individual data points with correct units Available since phyphox file format 1.7 (phyphox 1.1.0)
unitY
The unit of the y axis
optional, default: empty, the units will be appended to the label, but are also used to give values of individual data points with correct units Available since phyphox file format 1.7 (phyphox 1.1.0)
unitYperX
An explicit unit for slopes, if not set, phyphox will use "unitY / unitX".
optional, default: not set, phyphox will fallback to generate this from x and y unit. Available since phyphox file format 1.10 (phyphox 1.1.6)
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 to mark start/pause events and to switch to a system time scale (i.e. absolute date and time) on the x axis. Available since phyphox file format 1.12 (phyphox 1.1.8)
optional, 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 to mark start/pause events and to switch to a system time scale (i.e. absolute date and time) on the y axis. Available since phyphox file format 1.12 (phyphox 1.1.8)
optional, 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 to plot 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. Available since phyphox file format 1.12 (phyphox 1.1.8)
optional, default: false
systemTime
If set to true, time axes will start as a system time scale (they can always be switched by the user). Available since phyphox file format 1.12 (phyphox 1.1.8)
optional, default: false
hideTimeMarkers
If set to true, no red markers are shown to indicate times at which the experiment was stopped. Available since phyphox file format 1.14 (phyphox 1.1.10)
optional, default: false (= markers are visible)
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
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. Available since phyphox file format 1.19 (phyphox 1.2.0)
optional, default: false
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
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. Available since phyphox file format 1.15 (phyphox 1.1.11)
optional, default: false
lineWidth
Width of the graph line relative to the default width
optional, default: 1
color
Color of the graph line as six-digit RGB hex value or a named choice from the phyphox Colors
optional, default: phyphox orange
history
Deprecation warning: This feature has been marked as depricated 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))
optional, default: 1

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 similar 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 needs to have exactly the same value, so the value has to be provide for every single data point. However, you cannot just provide arbitrarily distributed data point.

The color map creates a lattice from the provided points, which is then colored. For this, an additional paramtere "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 connection to the next row won't match up. If you need to plot random data pairs, you might want to check our 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 monotonous instead of the x axis.

The color map plot introduces the following additional attributes:

labelZ
The label of the z axis
optional, default: empty, but you should always label your axes...
logZ
If set to true, the x axis will be on a logarithmic scale
optional, default: false
zPrecision
The number of significant digits on the z axis.
optional, default: 3
minZ
Lowest value on the z axis. Only applied if scaleMinZ = fixed
optional, default: 0
maxZ
Highest value on the z axis. Only applied if scaleMaxZ = fixed
optional, default: 0
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, 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 minimum to maxZ.
optional, default: auto
mapWidth
Number of data points per line.
optional, but a color map chart won't work without this.
mapColor[n]
n-th color in the color map
optional, if none are defined, phyphox uses a black-orange-white color gradient

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 a 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. You can define different colors (color attribute), line widths (lineWidth) and plot styles (style as line, dots, vbars or hbars) by applying these attributes to the input tag instead of the graph tag. Here, it does not matter if you define these for the x or y axis, but you should make sure that all inputs are assigned to an axis and that they are ordered correctly.

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: 1.0
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>
    <trigger>ID</trigger>
</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.

Since version 1.8 (phyphox 1.1.3) in addition to defining in and out buffer (or usually as an alternative), you can set a trigger tag defining an id. This triggers matching processes with the same id like a network connection (the only example at the time of this writing).

label
A label for this element
required


View-Element: depth-gui

Available since phyphox file format 1.14 (phyphox 1.1.10) 

<depth-gui label="LABEL" />

This is a preview and control for a depth input, showing a preview of the camera and allowing for selecting an acquisition area, an aggregation method and switching cameras. At the moment, you can only set the label. Note that this only makes sense if you also use a depth input in the configuration.

View-Element: image

Available since phyphox file format 1.18 (phyphox 1.1.16) 

    <image src="RESOURCE" scale="1.0" lightFilter="none" darkFilter="none" />

Display an image with the file name RESOURCE. Typically, RESOURCE is a png or jpg image (these are natively supported on both iOS and Android, hoping for SVG support on iOS eventually) that is placed in the resource folder "res" in a zip file along with the experiment XML file. So, for example, instead of sharing experiment.phyphox you would share a zip file that contains experiment.phyphox together with a folder called "res" that contains an image "demo.jpg". The image element would then set RESOURCE to "demo.jpg" (not res/demo.jpg), i.e. <image src="demo.jpg" />.

src
The file name of the image that should be displayed. (Relative to the resource folder.)
required
scale
Scales the size of the image. By default (scale="1.0") the image is shown in full width. The factor is relative to this, so scale="0.5" sets it to half the width of the view.
optional, default: 1.0
lightFilter
A filter that should be applied to the image if the interface of phyphox is in light mode. Currently, there are two options: none leaves the image as is. invert inverts the colors of the image.
optional, default: none
darkFilter
A filter that should be applied to the image if the interface of phyphox is in dark mode. Currently, there are two options: none leaves the image as is. invert inverts the colors of the image.
optional, default: none

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

Block: network

The network block can define network connections that allow requesting values from or sending data to a service on a network (local or internet). This function is documented on a separate page.

Block: events

The events block was introduced with file format 1.12 (phyphox version 1.1.8) as a temporary solution to store event and time reference data. It will be supported in the future to allow for reading old experiment state files, but at the time of this writing, there will be no specific use for this feature once the experiment state is stored in a form that separates measured data (and events) from the phyphox-configuration file.

The events block contains a list of event-block with tags corresponding to any known event, which are currently start and pause. Each event needs to have an attribute experimentTime and an attribute systemTime giving the experiment time (seconds since first start, ignoring pauses) and the system time (milliseconds since 1970) of the event. 

<phyphox version="1.0">
    ...
    <events>
        <start experimentTime="0.0" systemTime="1608126693705"/>
        <pause experimentTime="1.3307273210000001" systemTime="1608126695035"/>
        <start experimentTime="1.3307273210000001" systemTime="1608126696552"/>
        <pause experimentTime="2.310827263" systemTime="1608126697532"/>
        ...
    </events>
    ...
</phyphox>
Retrieved from "http://phyphox.org/wiki/index.php?title=Phyphox_file_format&oldid=21532"