ForceCalibrationItem

lumicks.pylake.calibration.ForceCalibrationItem

class ForceCalibrationItem(dictionary=None, *, voltage=None, sum_voltage=None, driving=None)

calibration_params()

Returns parameters to calculate the same calibration as the one performed by Bluelake

Examples

import lumicks.pylake as lk

f = lk.File("passive_calibration.h5")
calibration = f.force1x.calibration[1]  # Grab a calibration item for force 1x

# Slice the data corresponding to the calibration we want to reproduce.
calib_slice = f.force1x[calibration]

# De-calibrate to volts using the calibration that was active before this slice.
previous_calibration = calib_slice.calibration[0]
calib_slice = calib_slice / previous_calibration.force_sensitivity

calibration_params = previous_calibration.calibration_params()
new_calibration = lk.calibrate_force(calib_slice.data, **calibration_params)
new_calibration.plot()

# Make a new calibration, but change the amount of blocking
less_blocking_params = calibration_params | {"num_points_per_block": 200}
less_blocking = lk.calibrate_force(calib_slice.data, **less_blocking_params)
less_blocking.plot()

# Recalibrate the force channels
recalibrated_force1x = f.force1x.recalibrate_force(less_blocking)

clear() → None.  Remove all items from D.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

plot(show_excluded=False, show_active_peak=False, data_range=None)

Plot the fitted spectrum

Parameters:

• show_excluded (bool) – Show fitting regions excluded from the fit

• show_active_peak (bool) – Show active calibration peak when available

• data_range ((float, float)) – Optional frequency range to plot the calibration data for. If not specified, the fitted frequency range is plotted.

Raises:

ValueError – If specifying show_active_peak=True for a passive calibration.

plot_spectrum_residual()

Plot the residuals of the fitted spectrum.

This diagnostic plot can be used to determine how well the spectrum fits the data. While it cannot be used to diagnose over-fitting (being unable to reliably estimate parameters due to insufficient information in the data), it can be used to diagnose under-fitting (the model not fitting the data adequately).

In an ideal situation, the residual plot should show a noise band around 1 without any systematic deviations.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

power_spectrum_params()

Returns parameters with which the power spectrum was calculated

Examples

import lumicks.pylake as lk

f = lk.File("passive_calibration.h5")
calibration = f.force1x.calibration[1]  # Grab a calibration item for force 1x

# Slice the data corresponding to the calibration we want to reproduce.
calib_slice = f.force1x[calibration]

# De-calibrate to volts using the calibration that was active before this slice.
previous_calibration = calib_slice.calibration[0]
calib_slice = calib_slice / previous_calibration.force_sensitivity

power_spectrum_params = previous_calibration.power_spectrum_params()
power_spectrum = lk.calculate_power_spectrum(calib_slice.data, **power_spectrum_params)
power_spectrum.plot()

recalibrate_with(**params)

Returns a calibration structure with some parameters overridden.

For a full list of parameters to override, please see calibrate_force()

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

property active_calibration

Returns whether it was an active calibration or not

Calibrations based on active calibration are less sensitive to assumptions about the bead diameter, viscosity, distance of the bead to the flow cell surface and temperature. During active calibration, the trap or nano-stage is oscillated sinusoidally. These oscillations result in a driving peak in the force spectrum. Using power spectral analysis, the force can then be calibrated without prior knowledge of the drag coefficient.

While this results in improved accuracy, it may lead to an increase in the variability of results.

Note

When active calibration is performed using two beads, correction factors must be computed which account for the reduced flow field that forms around the beads due to the presence of a second bead.

property applied_at

Time the calibration was applied in nanoseconds since epoch

property backing

Statistical backing (%)

The support or backing is the probability that a repetition of the measurement that produced the data we fitted to will, after fitting, produce residuals whose squared sum is greater than the one we initially obtained. More informally, it represents the probability that a fit error at least this large should occur by chance.

property bead_diameter

Bead diameter (microns)

property chi_squared_per_degree

Chi squared per degree of freedom

This quantity is given by the sum of squares divided by the number of degrees of freedom and should be close to unity for a good fit.

property corner_frequency

Estimated corner frequency (Hz)

Note

When the hydrodynamically correct model is used and a height is provided, this returns the value in bulk. When this model is used, the height dependence due to the change in drag coefficient is captured by the model. In this case, any remaining height-dependent variation is due to optical aberrations.

When using the simpler model or when not providing the height, the estimated corner frequency will depend on the distance to the surface resulting in a lower corner frequency near the surface.

property corner_frequency_factor: float | None

Corner frequency factor (-)

When fitting power spectra, the initial fitting range may be adapted to exclude low SNR points. This is done via a heuristic that excludes all frequencies above corner_frequency_factor times the corner frequency. This reduces the effect of the noise floor as well as slightly biased diode calibrations at lower trap powers.

property corner_frequency_std_err

Corner frequency std error (Hz)

Asymptotic standard error of the fit. See corner_frequency for more information on this parameter.

property diffusion_constant

Fitted diffusion constant (µm²/s)

Note

When the hydrodynamically correct model is used and a height is provided, this returns the value in bulk. When this model is used, the height dependence due to the change in drag coefficient is captured by the model.

When using the simpler model or when not providing the height, the estimated diffusion constant will depend on the distance to the surface resulting in a lower diffusion constant near the surface.

property diffusion_constant_volts

Fitted diffusion constant (V²/s)

Note

When the hydrodynamically correct model is used and a height is provided, this returns the value in bulk. When this model is used, the height dependence due to the change in drag coefficient is captured by the model.

When using the simpler model or when not providing the height, the estimated diffusion constant will depend on the distance to the surface resulting in a lower diffusion constant near the surface.

property diffusion_volts_std_err

Diffusion constant std error (V²/s)

Asymptotic standard error of the fit. See diffusion_volts for more information on this parameter.

property diode_calibration: lumicks.pylake.force_calibration.calibration_models.DiodeCalibrationModel | None

Diode calibration model

The detector used to measure forces has a limited bandwidth. This bandwidth is typically characterized by two parameters, a diode frequency and relaxation factor (which gives the fraction of light that is instantaneously transmitted).

Some force detection diodes have been pre-calibrated in the factory. For these sensors, this property will return a model that will allow you to calculate the diode parameters at a particular trap sum power.

Examples

import lumicks.pylake as lk

f = lk.File("passive_calibration.h5")
item = f.force1x.calibration[0]  # Grab a calibration item for force 1x
diode_model = item.diode_calibration  # Grab diode model
diode_parameters = diode_model(item.trap_power)  # Grab diode parameters

# Verify that the calibration parameters at this trap power are the same as we found
# in the item in the first place.
assert diode_parameters["fixed_diode"] == item.diode_frequency
assert diode_parameters["fixed_alpha"] == item.diode_relaxation_factor

property diode_frequency

Diode filtering frequency (Hz).

The measured voltage (and thus the shape of the power spectrum) is determined by the Brownian motion of the bead within the trap as well as the response of the PSD to the incident light.

For “fast” sensors, this second contribution is negligible at the frequencies typically fitted, while “standard” sensors exhibit a characteristic filtering where the PSD becomes less sensitive to changes in signal at high frequencies. This filtering effect is characterized by a constant that reflects the fraction of light that is transmitted instantaneously (the diode relaxation factor) and a corner frequency (diode_frequency).

Note

Some systems have characterized diodes. In these systems, this is not a fitted but fixed value. Please refer to the property fitted_diode to determine whether the diode frequency was fixed (pre-characterized) or fitted.

property diode_frequency_std_err

Diode frequency std error (-)

Asymptotic standard error of the fit. See diode_frequency for more information on this parameter.

property diode_relaxation_factor

Diode relaxation factor (-)

The measured voltage (and thus the shape of the power spectrum) is determined by the Brownian motion of the bead within the trap as well as the response of the PSD to the incident light.

For “fast” sensors, this second contribution is negligible at the frequencies typically fitted, while “standard” sensors exhibit a characteristic filtering where the PSD becomes less sensitive to changes in signal at high frequencies. This filtering effect is characterized by a constant that reflects the fraction of light that is transmitted instantaneously (the diode relaxation factor) and a corner frequency (diode_frequency).

A relaxation factor of 1.0 results in no filtering. This property will return None for fast sensors (where the diode model is not taken into account).

Note

Some systems have characterized diodes. In these systems, this is not a fitted but fixed value. Please refer to the property fitted_diode to determine whether the diode frequency was fixed (pre-characterized) or fitted.

property diode_relaxation_factor_std_err

Relaxation factor std error (-)

Asymptotic standard error of the fit. See diode_relaxation_factor for more information on this parameter.

property displacement_sensitivity

Displacement sensitivity (µm/V)

The displacement sensitivity corresponds to the conversion factor from raw sensor voltages to the bead displacement from the trap center.

In passive calibration, it is calculated from the ratio of the expected diffusion constant (in µm²/s) to the diffusion constant quantified from the power spectral fit (in V²/s). The former depends on the drag coefficient which in turn is linearly dependent on the viscosity and bead diameter, as well as non-linearly dependent on the distance from the flow-cell surface.

In active calibration with a nano-stage, the displacement sensitivity is determined by applying a known displacement to the fluid in the flow-cell. Using parameters from the passive fit, we can calculate an expected motion of the bead in response to this fluid motion. The driving peak can be observed on the position sensitive detector (in Volts), while we know its motion in (microns). The advantage of active calibration is that it does not rely as strongly on a theoretical drag coefficient and is therefore less sensitivity to the input parameters viscosity, bead diameter and distance to the surface.

To recalibrate distance channels, simply multiply them by the ratio of displacement sensitivities of the old and new calibration.

property displacement_sensitivity_std_err

Displacement sensitivity std error (µm/V)

Obtained through Gaussian error propagation. See displacement_sensitivity for more information.

property distance_to_surface

Distance from bead center to surface (µm)

property driving

Driving signal used for active calibration

property driving_amplitude

Quantified driving amplitude (µm)

This property corresponds to the driving amplitude quantified from the position signal measuring the stage or trap motion.

property driving_frequency

Quantified frequency (Hz)

This property corresponds to the driving frequency quantified from the position signal measuring the stage or trap motion.

property driving_frequency_guess

Driving frequency guess (Hz)

The force calibration procedure requires an initial guess of the frequency driving the active calibration procedure. This frequency is typically the requested driving frequency of the nano-stage. This initial estimate is refined using power spectral estimation. See driving_frequency for the achieved driving frequency.

property driving_power

Driving power at the position sensitive detector (V²)

This property corresponds to the driving power measured at the force detector (in Volts). The estimated driving_frequency is used to window the calibration data such that the driving peak ends up on exactly one frequency bin which can then subsequently be quantified. After quantification of the peak magnitude, the thermal background is subtracted to obtain the driving power.

property driving_sample_rate: float | None

Return the data sample rate of the driving input (if applicable)

property excluded_ranges

Frequency exclusion ranges (Hz)

When fitting power spectra, specific frequency intervals of the spectrum can be ignored to exclude noise peaks. This property returns a list of these intervals in Hertz.

property fast_sensor

Fast sensor

Some force sensors include a parasitic filtering effect. When this flag is set to False, the model includes such a parasitic filtering effect. When this flag is True, no such effect is included in the model. This flag should only be used for fast sensors (sensors where the sensor does not exhibit a frequency dependent attenuation over the measured bandwidth).

property fit_range: tuple[float, float] | None

Spectral frequency range used for calibration (Hz)

When fitting power spectra, an initial frequency range is selected to perform the fit on. This initial range may be adapted during fitting to exclude lower SNR points. This property returns the final frequency range in Hertz.

property fitted_diode

Diode parameters were fitted

The measured voltage (and thus the shape of the power spectrum) is determined by the Brownian motion of the bead within the trap as well as the response of the PSD to the incident light.

For “fast” sensors, this second contribution is negligible at the frequencies typically fitted, while “standard” sensors exhibit a characteristic filtering where the PSD becomes less sensitive to changes in signal at high frequencies. This filtering effect is characterized by a constant that reflects the fraction of light that is transmitted instantaneously (the diode relaxation factor) and a corner frequency (diode_frequency).

Some systems have characterized diodes. In these systems, this is not a fitted but fixed value. This property is False for calibrations where the diode frequency and relaxation factor were fixed (pre-characterized).

property force_sensitivity

Force sensitivity (pN/V)

The force sensitivity provides the calibration factor for converting sensor readouts from voltages to forces. It is given by the product of the displacement sensitivity and trap stiffness.

To recalibrate force channels, simply multiply them by the ratio of force sensitivities of the old and new calibration.

property has_data

Returns whether the calibration item has the raw data stored inside the item

property hydrodynamically_correct

Hydrodynamically correct model.

Force calibration involves fitting a model to the power spectrum of the calibration data.

This power spectrum has a Lorentian shape when the viscous drag force is proportional to the bead velocity. This is true when the velocity field is stationary around the bead. This model is only appropriate at low frequencies or when using small beads.

For larger beads, inertial effects start to play a role and the viscous force depends on the frequency of the motion and the second derivative of the bead position. These effects originate from waves generated by the interaction of the bead with the fluid, which in turn interact with the bead again. The hydrodynamically correct model takes these effects into account providing a more accurate description of the data especially for larger beads an at high frequencies.

property initial_fit_range: tuple[float, float] | None

Initial spectral frequency range used for calibration (Hz)

When fitting power spectra, an initial frequency range is selected to perform the fit on. This initial range may be adapted during fitting to exclude lower SNR points. This property returns the initial frequency range in Hertz.

property local_drag_coefficient

Measured local drag coefficient (kg/s)

Note

This parameter is only available when using active calibration. Represents the drag at the height the calibration was performed. For the value corrected back to bulk, see measured_drag_coefficient.

property measured_drag_coefficient

Measured bulk drag coefficient (kg/s)

Note

This parameter is only available when using active calibration.

For surface calibrations where the distance to the surface was provided, this represents the bulk value as the model is used to calculate it back to what the drag would have been in bulk.

property num_points_per_block

Number of points per block used for spectral down-sampling

property number_of_samples

Number of fitted samples (-).

property offset

Force offset (pN)

property rho_bead

Density of the bead (kg/m³).

Note

This parameter only affects hydrodynamically correct fits.

property rho_sample

Density of the medium (kg/m³).

Note

This parameter only affects hydrodynamically correct fits.

property sample_rate

Return the data sample rate

property start

Starting timestamp of this calibration

Examples

import lumicks.pylake as lk

f = lk.File("file.h5")
item = f.force1x.calibration[1]  # Grab a calibration item for force 1x

# Slice the data corresponding to this item
calibration_data = f.force1x[item.start : item.stop]

# or alternatively:
calibration_data = f.force1x[item]

property stiffness

Trap stiffness (pN/nm)

The trap stiffness gives a measure for how much force is required to displace the bead from the center of the optical trap. In passive calibration, this factor depends on a theoretical drag coefficient which is determined from the fluid viscosity, bead diameter and distance to the surface.

In active calibration fewer assumptions are required to calculate the trap stiffness and the drag coefficient is inferred from the measurement data.

property stiffness_std_err

Stiffness error (pN/nm)

Obtained through Gaussian error propagation. See stiffness for more information.

property stop

Stop time stored in the calibration item

property sum_voltage

Uncalibrated sum voltage on the detector

property temperature

Temperature (C)

property theoretical_bulk_drag

Expected bulk drag coefficient (kg/s)

The expected drag coefficient in bulk for a spherical particle is given by:

\[\gamma = 3 \pi \eta d\]

Where \(d\) represents the bead diameter, \(\eta\) the liquid viscosity and \(T\) the temperature.

property transferred_lateral_drag_coefficient

Drag coefficient from lateral calibration

When performing axial calibration, one can specify a known bulk drag coefficient obtained with active calibration and use that to calibrate the trap. This coefficient is then subsequently corrected for surface effects by applying Brenner’s law and used in passive calibration.

property trap_power

Average trap sum power in volts during calibration

Note that this property is only available for full calibrations with calibrated diodes.

property viscosity

Viscosity of the medium (Pa s)

property voltage

Uncalibrated voltage reading on the detector