is_clipped
Builtin index · Signal processing
result = is_clipped(x, [threshold=], [full_scale=], [tol=], [min_run=3])
Input: x, threshold, full_scale, tol, min_run · Output: result
What it is
x: a length-N real vector, Mat or Signal.
Overloads
One call shape — this function is not overloaded.
| Code | Input | Output | Description |
result = is_clipped(x, [threshold=], [full_scale=], [tol=], [min_run=3]) | x vector, Mat, or Signalx: a length-N real vector, Mat or Signal.threshold number, optionalthreshold=/full_scale= (optional numbers, interchangeable spellings, must be positive) set the magnitude a sample must reach to be a candidate.full_scale number, optionalthreshold=/full_scale= (optional numbers, interchangeable spellings, must be positive) set the magnitude a sample must reach to be a candidate.tol number, optionaltol= (optional number, default 1e-9 × threshold) is how nearly equal consecutive samples must be.min_run number, optional (default 3)min_run= (optional whole number ≥ 1, default 3) is how many consecutive samples make a run — min_run=1 degrades this to the plain "any sample at or beyond the threshold" test. | full_scale= numberoptional numbers, interchangeable spellings, must be positivetol= numberoptional number, default 1e-9 × thresholdmin_run= numberoptional whole number ≥ 1, default 3 | Returns a Bool: does x contain a flat run at an extreme. threshold=/full_scale= (optional numbers, interchangeable spellings, must be positive) set the magnitude a sample must reach to be a candidate; with neither, the record's own largest magnitude is used — safe because detection is run-based, see above. tol= (optional number, default 1e-9 × threshold) is how nearly equal consecutive samples must be; raise it for soft saturation. min_run= (optional whole number ≥ 1, default 3) is how many consecutive samples make a run — min_run=1 degrades this to the plain "any sample at or beyond the threshold" test. Errors on an empty record, and on an all-zero record with no explicit threshold (there is no level to test against). |
Examples
No documentation example calls this form yet. The Signal processing chapter is where one belongs.
How it works
is_clipped(x, [threshold=], [full_scale=], [tol=], [min_run=]) -> true/false, and find_clipping(x, ...) -> where. Same detection, two shapes, one parameter resolver (clip_params) so they cannot disagree. The test is a FLAT RUN at an extreme, not a threshold crossing. "Any sample within x% of full scale" fires on every healthy recording that uses its headroom -- a sine sampled near its peak legitimately touches the top of its range, and some sample is always the largest. What a clipped record has and an unclipped one does not is several CONSECUTIVE samples holding the same value: the converter emitting one code over and over because the input went where it could not follow. Consecutive samples of a real sine near its peak differ by about A*2*pi^2/N^2 for N samples per cycle, so equality separates the two without having to guess full scale. That is what makes the threshold default (the record's own largest magnitude) safe rather than a silent guess: on its own it flags nothing, it only picks the level the run test is applied at. Pass full_scale= when the converter's range is known -- then a flat run part-way up the range, which is a limiter rather than the converter, is correctly NOT reported. This catches HARD clipping. Soft/analogue saturation rounds the shoulder instead of flattening it and needs an explicit threshold= with a looser tol=; min_run=1 degrades the whole thing to the plain threshold test for a caller who really wants that.
From the note above this builtin in the interpreter, where the reasoning was written down as it was built.