Calibration¶
The flik-o-meter needs very little calibration, and most of it is automatic. This page says what the toolbox does by itself, what you set up by hand, and what cannot be calibrated at all.
| What | Who does it | When |
|---|---|---|
| Timebase: the board's true sample rate | The toolbox, automatically | At the start of every Measure flicker run (60 s) |
| The sensor's operating point: light level and gain | You, by placement and screen brightness | When you build the unit, and whenever a capture clips |
| Dark reference: the room light under every capture | The toolbox, if you ask for it | Once per run, when you want contrast figures |
| Latency | Not calibrated; measured | When you need stimulus timing in recordings |
Timebase: the board's clock¶
Every frequency the toolbox reports is computed from the sensor's samples and the rate at which they were taken. The board says it samples 2000 times a second, but its clock is a ceramic resonator that can be ±0.5 % off, and 0.5 % of 40 Hz is 0.2 Hz: twice the default tolerance, before anything has been measured. So at the start of each run the toolbox measures the real rate against the PC's clock and uses that.
What you do: nothing, except leave the default 60 seconds alone (Calibrate timebase in the dialog, --calibrate-s on the command line). During that minute the sensor can sit anywhere, because it is the clock being read, not the light, and the stimulus window does not open until it is done.
Why 60 seconds, and why not shorter. Short calibrations agree closely with each other, which makes them look accurate, but agreeing is not the same as being right. On the one unit measured so far, 10-second calibrations repeated to within a few hundredths of a hertz, yet all read about 530 parts per million (1.06 Hz in 2000) lower than four 60-second calibrations, which agreed with each other to within 4 ppm. That bias passes straight into every result: 0.04 Hz at 80 Hz, 40 % of the default tolerance. Why short windows are biased is not established. Sixty seconds is the shortest window shown to remove the bias, and where between 10 and 60 seconds it stops mattering has not been measured, so don't shorten it to save a minute. All of this comes from one board on one PC; another unit or another USB path could be biased differently, in either direction.
What the report records. Its notes say which calibration a run had, so an old report can be judged later:
[timebase: declared 2000 Hz, measured … Hz over a 60 s window]: calibrated normally;[timebase: calibration fit rejected — declared 2000 Hz used (…)]: the measurement could not be trusted (too little data, or a rate more than 2 % from 2000, which means the stream stalled or fell out of step rather than a resonator error), so every frequency in the report is scaled by the uncorrected rate and may be up to 0.5 % out;[timebase: not calibrated …]: calibration was switched off.
How the measurement works is on the technical reference.
The sensor's operating point¶
The sensor's output must stay inside the range the board can read (0–1023 counts) through the whole flicker cycle. Two things set where it sits: the light reaching it and the sensor's fixed gain.
Don't make the hood light-tight¶
This one costs an afternoon if you don't know it. Seal the sensor completely against the screen and the dark phase of the flicker drives the reading to 0: with no room light at all there is nothing to hold the dark phase above zero, and the sensor's output cannot go below it. Every target then reports clipped and fails, while measuring perfectly: the first fully hooded test gave a frequency error of −0.019 Hz and 0.12 ms of drift on all nine targets, and scored 0 out of 9.
The sign is a low end of exactly 0 with the top nowhere near 1023 (adc 0-190, say): bottomed out, with gain to spare. Turning the brightness down makes it worse, and so does adding gain, which multiplies a dark phase of 0 by more and pushes the bright phase toward the other limit.
The fix is to let a little room light in: rest the wand lightly so a hair of light reaches the sensor around the tip, or leave a small gap at the edge of a hood. That lifts the dark phase clear of zero (adc 6-222 in the run that then passed 9 out of 9) without changing the swing or the frequency. This is the right operating point, not a workaround.
Too much light¶
If the bright phase saturates the sensor, the top of the adc range sits at the same value on every target. Turn the screen brightness down, or lower the sensor's gain (the build guide's Gain and other adjustments). Note that the sensor saturates somewhat below 1023, which the clipped check does not catch (#555); only a reading of exactly 1023 counts as clipped.
Dark reference¶
The room light that keeps the dark phase off zero is also a constant offset under every capture. That doesn't matter for frequency, but it makes any contrast figure computed from the raw readings come out too low, by an amount that depends on the room. The dark reference measures that offset so it can be subtracted.
How to take one. Tick Dark reference first in the dialog (--dark-reference on the command line). Before the first target the window says DARK REFERENCE. Place the sensor exactly as you will for measuring, on the first target's spot or on the sync square, with the same light gap, and press SPACE. The whole screen is held black for one capture.
What it adds. A modulation depth and a noise floor for every target, described on Interpreting results. It changes no pass or fail.
One per run. The reference is taken where the first target is measured. If you move the sensor somewhere else with different surroundings, or the room light changes, start a fresh run; the trough_below_dark flag tells you when the reference no longer matches.
The latency procedure needs no dark reference: its trials are dark before every onset, and each trial's own dark period is its baseline.
Latency¶
The delay from a stimulus marker to the light is measured, not calibrated: Using it explains how. Nothing in the toolbox applies a measured latency automatically. The analysis has its own separate allowance for the delay before a visual response begins (the onset offset set in the design), which is a property of the visual system, not of the display.
What cannot be calibrated¶
The sensor's counts are not luminance. The OPT101 is most sensitive to red and near-infrared light, while luminance, what a design's mean_luminance and the photosensitivity grading use, is weighted toward green, as the eye is. So:
- counts compare fairly only between targets of the same colour: one pattern, frequency or build against another;
- a coloured target or a picture compared with a white one says how much light this sensor saw, not how bright it looks. Measured once: a picture target whose
mean_luminanceis 0.275 of white swung 0.65 of a white square's counts, because the sensor sat on a red-and-blue patch that is dim to the eye but bright to the OPT101; - the modulation depth is in sensor units, good for comparing one stimulus or build with another, not a perceived contrast;
- absolute luminance in cd/m² is out of reach.
A contrast or luminance measurement needs a different sensor, weighted like the eye, and for cd/m² a calibration against a reference meter: see the build guide's photometric variant. For a picture stimulus, use a neutral grey test image.