detect_saturation
Builtin index · Signal processing
result = detect_saturation(x, adc_bits, [full_scale=1.0])
Input: x, adc_bits, full_scale · Output: result
What it is
x: a length-N real vector, Mat or Signal; adc_bits: a whole number 1–32, positional or as adc_bits=/bits= — required, since there is no rail to check against without it. Has x hit the rails of an adc_bits-bit converter: the clipping question for a converter whose range is *known* rather than inferred, so no flat run is required and a single sample sitting on a rail already counts. full_scale= (optional number, default 1.0, must be positive) sets a range symmetric about zero, [-full_scale, +full_scale]: signal-processing records are bipolar by default, and a unipolar reading would report the entire negative half as railed. The default is the stated convention dbfs already set, not a value read off the data — inferring the range from the record would make the answer trivially "yes" for every record.
Overloads
One call shape — this function is not overloaded.
| Code | Input | Output | Description |
result = detect_saturation(x, adc_bits, [full_scale=1.0]) | x vector, Mat, or Signalx: a length-N real vector, Mat or Signal.adc_bits numberadc_bits: a whole number 1–32, positional or as adc_bits=/bits= — required, since there is no rail to check against without it.full_scale number, optional (default 1.0)full_scale= (optional number, default 1.0, must be positive) sets a range symmetric about zero, [-full_scale, +full_scale]: signal-processing records are bipolar by default, and a unipolar reading would report the entire negative half as railed. | saturated —a Booltotal NumNums, samples on the top rail, the bottom rail, and eitherfraction Numa Num, total / Ntop_code NumNums, the code geometry used — note top_code = vmax - lsbbits Numa Num | Returns a Record with fields saturated (a Bool), high, low, total (Nums, samples on the top rail, the bottom rail, and either), fraction (a Num, total / N), lsb, vmin, vmax, top_code (Nums, the code geometry used — note top_code = vmax - lsb), and bits (a Num). Errors on an empty record. |
Examples
No documentation example calls this form yet. The Signal processing chapter is where one belongs.
How it works
detect_saturation(x, adc_bits, [full_scale=]) -- the same question for a converter whose range is KNOWN rather than guessed, and deliberately a different test: no flat run is required, because when the rail is a number you were handed, a single sample sitting on it is already evidence and demanding a run would lose exactly the short excursions that matter most. The code geometry comes from numeric::noise::code_step, the same one adc quantises with, so the detector and the simulator cannot drift into two slightly different converters. The consequence worth knowing: codes run 0 ..= 2^bits - 1, so the top code is full_scale - lsb, NOT full_scale. A check that looks for samples at exactly full_scale finds none, ever. full_scale defaults to 1.0 -- the stated convention dbfs already set, not a value read off the data. Inferring the range from the record would make the answer trivially "yes" for every record, since the largest sample is always at the largest sample.
From the note above this builtin in the interpreter, where the reasoning was written down as it was built.