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 analyzed as fast as possible (capped at roughly 100 executions per second). However, if you need to acquire a certain amount of data first (for example when recording from the microphone) or if the results only change if the user changes a parameter, you can define the attributes sleep, dynamicSleep, requireFill and/or onUserInput to pause the analysis loop.

Attributes

sleep: The minimum time in seconds before the whole analysis block is executed again after the last execution has finished. Decimal values are allowed. Independently of this attribute (and of dynamicSleep), both apps pause at least about 10 ms between runs, so the analysis never runs faster than roughly 100 Hz - the default of 0 simply means as fast as that limit allows.; optional, float, default: 0.0
dynamicSleep: Name of a data container supplying the minimum time in seconds before the whole analysis block is executed again, so the sleep time can be set by the analysis result itself. If the container is empty, the value from sleep is used instead.; added in 1.5 optional
onUserInput: If true, the analysis block is not executed again unless the user changes the content of an input view.; optional, boolean, default: false
requireFill: Name of a data container that needs to be filled before the block runs. requireFillThreshold or requireFillDynamic defines the required number of elements (default 1); if the container holds fewer, the analysis block is skipped. The first run after opening or starting the experiment is exempt from this gate, so the initialization pass (cycle 0) runs even while the required container is still empty - without the exemption most experiments using requireFill would never initialize. (Decided 2026-08-24.) STOPPING does not exempt anything: the passes that run while an experiment is paused are gated like any other. Both platforms had this wrong in opposite ways and both were corrected 2026-08-26 - the exemption is armed by opening and by starting, never by stopping. It matters because a paused pass runs with the inputs already consumed: exempting it lets the modules clear their outputs, which destroyed the recorded results of an audio experiment as soon as anything read them over the remote interface.; added in 1.16 optional
requireFillThreshold: A static integer setting the number of elements the container named by requireFill must hold.; added in 1.16 optional, integer, default: 1
requireFillDynamic: Name of a data container supplying the required number of elements for requireFill dynamically. If it is empty, the value from requireFillThreshold is used instead.; added in 1.16 optional
timedRun: Enable the timed-run setting by default. This acts only as a preset; the user can still deactivate it from the main menu.; added in 1.10 optional, boolean, default: false
timedRunStartDelay: Start delay in seconds for the timed-run setting. This acts only as a preset, and does not enable the function by itself - see timedRun.; added in 1.10 optional, float, default: 3.0
timedRunStopDelay: Stop delay in seconds for the timed-run setting. This acts only as a preset, and does not enable the function by itself - see timedRun.; added in 1.10 optional, float, default: 10.0

An earlier attribute optimization was removed in phyphox file format 1.10 (phyphox 1.1.6); it barely added any value but increased confusion significantly. It is ignored if present in an old file.

<phyphox version="...">
    ...
    <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¶

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 a few modules, which is noted where applicable.

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 set as an attribute of the analysis module tag. As an example, the threshold module searches for 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 modules support a new attribute that makes it possible to determine whether the module should be executed in each analysis cycle or only in specific cycles. For this, each run of the analysis process (a cycle) is numbered. When the user opens the experiment and before they press 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 cycles 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 cycles 0, 3, 5, 6, 7, 10 and then every subsequent cycle.

Attributes accepted by every module

cycles: Which analysis cycles this module runs in, as a space-separated list of numbers and dash-ranges with open ends allowed, e.g. "0 3 5-7 10-". Cycle 0 runs once when the experiment is opened, before the user presses start. Unset, the module runs in every cycle.; added in 1.10 optional

Attributes accepted by every <input>

<input as="STRING" type="STRING" keep="BOOLEAN">BUFFER</input>

as: Which slot of the module this input feeds.; optional
type: Whether the text names a data container, is a literal value, or stands for a constant empty buffer.; optional, one of buffer, value, empty, default: buffer
keep: Whether the data container keeps its contents after being read. False clears it, so each dataset is processed once.; optional, boolean, default: false
clear: Deprecated in file format 1.17 in favor of keep, which is the more intuitive spelling. clear=true corresponds to keep=false.; Deprecated. Use keep instead.; optional, boolean, default: true

Attributes accepted by every <output>

<output as="STRING" append="BOOLEAN">BUFFER</output>

as: Which slot of the module this output receives.; optional
append: Whether new data is appended to the container rather than replacing its contents.; optional, boolean, default: false
clear: Deprecated in file format 1.17 in favor of append. clear=true corresponds to append=false.; Deprecated. Use append instead.; optional, boolean, default: true

The values of the type attribute of inputs and outputs ("buffer", "value", "empty") are matched case-insensitively, like every enumerated attribute value.

Analysis modules never abort the experiment on bad parameters. A present but invalid parameter value — such as NaN or an infinity where a count or width is expected — puts the module into an intermediate error state: it outputs NaN where a single value is expected and nothing where a list is expected, and recovers as soon as valid data arrives. An absent optional input keeps its documented default. Non-finite values that are mathematically meaningful, such as an infinite threshold or bound, participate in comparisons normally and are not errors. Configuration that can never work, on the other hand, is a load error rather than a runtime state and rejects the file.

Buffers bound to interactive view elements (edit, toggle, dropdown, slider) are not exempt from clearing: an analysis input without keep="true" clears them like any other buffer, and the element then re-initializes both the buffer and the displayed value to its default. Use keep="true" on such inputs to preserve the user's setting across analysis cycles.

List of analysis modules¶

The specific mappings, attributes and functionality of the analysis modules are documented by category: