psiaudio.calibration module

class BaseCalibration(reference, attrs=None)

Bases: object

Assumes that the system is linear for a given frequency

Parameters:

  • frequency (1D array) – Frequencies that system sensitivity was measured at.

  • sensitivity (1D array) – Sensitivity of system in dB

  • attrs ({None, dict}) – Information regarding the calibration (e.g., the filename the calibration was loaded from).

get_attenuation(frequency, voltage, level)
get_db(*args)

Convert voltage into dB re reference unit for calibration (e.g., dB SPL).

This function accepts one or two arguments. If one argument is provided, it must be a series or dataframe. For the series, the index must be frequency (in Hz). For the dataframe, the columns must be frequency (in Hz). This plays well with the output of other functions in this module (e.g., ~util.psd_df).

If two arguments are provided, the first argument must be frequency and the second voltage.

get_gain(frequency, level, attenuation=0)
get_level(voltage, frequency=1000.0)

Returns level in calibrated units (e.g., Pascals if reference is SPL).

get_sens(frequency)
get_sf(frequency, level, attenuation=0)
set_fixed_gain(fixed_gain)
class BaseFrequencyCalibration(reference, attrs=None)

Bases: BaseCalibration

Base class for calibrations that vary over frequencies.

classmethod from_db(frequency, level, vrms=1, **kwargs)

Generates a calibration object based on the recorded level in dB re. reference.

Parameters:

  • frequency (array-like) – List of frequencies (in Hz)

  • level (array-like) – List of magnitudes in dB re. reference (e.g., speaker output in SPL) for the specified RMS voltage.

  • vrms (float) – RMS voltage (in Volts)

  • initialization. (Additional kwargs are passed to the class)

classmethod from_pascals(frequency, magnitude, vrms=1, **kwargs)

Generates a calibration object based on the recorded value (in Pascals)

Parameters:

  • magnitude (array-like) – List of magnitudes (e.g., speaker output in Pa) for the specified RMS voltage.

  • frequency ({None, array-like}) – List of frequencies (in Hz)

  • vrms (float) – RMS voltage (in Volts)

  • initialization. (Additional kwargs are passed to the class)

classmethod from_spl(frequency, spl, vrms=1, **kwargs)
exception CalibrationError(message)

Bases: Exception

Base exception for calibration errors.

Parameters:

message (str) – Description of the calibration error.

exception CalibrationNFError(frequency, snr)

Bases: CalibrationError

Exception raised when noise floor/SNR limits are violated.

Parameters:

  • frequency (float) – Frequency at which error occurred.

  • snr (float) – Measured SNR value in dB.

exception CalibrationTHDError(frequency, thd)

Bases: CalibrationError

Exception raised when total harmonic distortion (THD) exceeds limits.

Parameters:

  • frequency (float) – Frequency at which THD error occurred.

  • thd (float) – The THD value measured (in %).

class FlatCalibration(sensitivity, fixed_gain=0, reference=None, attrs=None)

Bases: BaseCalibration

Calibration that assumes a flat sensitivity profile across frequencies.

classmethod as_attenuation(vrms=1, **kwargs)
classmethod from_db(level, vrms=1, **kwargs)

Generates a calibration object based on the recorded level (in dB)

Parameters:

  • levels (array-like) – List of magnitudes in dB re desired unit (e.g., speaker output in SPL) for the specified RMS voltage.

  • vrms (float) – RMS voltage (in Volts)

  • initialization. (Additional kwargs are passed to the class)

classmethod from_mv_pa(mv_pa, **kwargs)

This converts sensitivity to dB SPL per V

classmethod from_pascals(magnitude, vrms=1, **kwargs)

Generates a calibration object based on the recorded value (in Pascals)

Parameters:

  • frequency (array-like) – List of freuquencies (in Hz)

  • magnitude (array-like) – List of magnitudes (e.g., speaker output in Pa) for the specified RMS voltage.

  • vrms (float) – RMS voltage (in Volts)

  • initialization. (Additional kwargs are passed to the class)

classmethod from_spl(spl, vrms=1, **kwargs)
get_mean_sf(flb, fub, spl, attenuation=0)
get_sens(frequency)
to_mv_pa()
classmethod unity()

Passthrough calibration allowing signal level to be specified in Vrms.

class InterpCalibration(frequency, sensitivity, fixed_gain=0, phase=None, reference=None, attrs=None)

Bases: BaseFrequencyCalibration

Use when calibration is not flat (i.e., uniform) across frequency.

Parameters:

  • frequency (array-like, Hz) – Calibrated frequencies (in Hz)

  • sensitivity (array-like, dB(V/Pa)) – Sensitivity at calibrated frequency in dB(V/Pa) assuming 1 Vrms and 0 dB gain. If you have sensitivity in V/Pa, just pass it in as 20*np.log10(sens).

  • fixed_gain (float) –

    Fixed gain of the input or output. The sensitivity is calculated using a gain of 0 dB, so if the input (e.g. a microphone preamp) or output (e.g. a speaker amplifier) adds a fixed gain, this needs to be factored into the calculation.

    For input calibrations, the gain must be negative (e.g. if the microphone amplifier is set to 40 dB gain, then provide -40 as the value).

get_mean_sf(flb, fub, level, attenuation=0)
get_phase(frequency)
get_sens(frequency)
make_eq_filter(fs, fl=None, fh=None, window='hann', ntaps=1001, max_correction=30, target_level=80, target_rms=1)

Generate a FIR filter that can be used to equalize a waveform

Parameters:

target_level ({None, float}) – If None, FIR filter is configured so that

class PointCalibration(frequency, sensitivity, fixed_gain=0, reference=None, attrs=None)

Bases: BaseFrequencyCalibration

Calibration class based on discrete measured points.

Use when interpolation between specified frequencies is not desired.

Parameters:

  • frequency (array_like) – Calibrated frequencies (in Hz).

  • sensitivity (array_like) – Sensitivity values at calibrated frequencies.

  • fixed_gain (float, optional) – Fixed system gain, by default 0.

  • reference (str, optional) – Unit reference for calibration.

  • attrs (dict, optional) – Additional metadata/attributes.

get_mean_sf(flb, fub, level, attenuation=0)
load_demo_starship()