bab

docs/theory/force_calibration/surface.rst

@@ -41,7 +41,7 @@ Mathematical background
 
 .. _hydro_math:
 
-**Hydrodynamically correct theory**
+**Hydrodynamically correct theory (lateral)**
 
 When approaching the surface, the drag experienced by the bead depends on the distance between the
 bead and the surface of the flow cell. An approximate expression for the frequency dependent drag is

docs/tutorial/force_calibration.rst

@@ -197,57 +197,6 @@ However, if we do not provide the height above the surface, we can see that the
     Consequently, when this model is selected, this parameter affects both passive and active calibration.
     For more information on this see the :doc:`theory section on force calibration</theory/force_calibration/force_calibration>` section.
 
-.. _bead_bead_tutorial:
-
-Active calibration with two beads far away from the surface
------------------------------------------------------------
-
-.. warning::
-
-    The implementation of the coupling correction models is still alpha functionality.
-    While usable, this has not yet been tested in a large number of different scenarios.
-    The API can still be subject to change *without any prior deprecation notice*!
-    If you use this functionality keep a close eye on the changelog for any changes that may affect your analysis.
-
-When performing active calibration with two beads, we get a lower fluid velocity around the beads than we would with a single bead.
-This leads to a smaller voltage readout than expected and therefore a higher displacement sensitivity (microns per volt).
-Failing to take this into account results in a bias.
-Pylake offers a function to calculate a correction factor to account for the lower velocity around the bead.
-
-.. note::
-
-    For more information on how these factors are derived, please refer to the :ref:`theory<bead_bead_theory>` section on this topic.
-
-Appropriate correction factors for oscillation in x can be calculated as follows::
-
-    factor = lk.coupling_correction_2d(dx=5.0, dy=0, bead_diameter=bead_diameter, is_y_oscillation=False)
-
-Here `dx` and `dy` represent the horizontal and vertical distance between the beads.
-Note that these refer to *center to center distances* (unlike the distance channel in Bluelake, which represents the bead surface to surface distance).
-Note that all three parameters have to be specified in the same spatial unit (meters or micron).
-The final parameter `is_y_oscillation` indicates whether the stage was oscillated in the y-direction.
-
-The obtained correction factor can be used to correct the calibration factors::
-
-    Rd_corrected = factor * calibration["Rd"].value
-    Rf_corrected = calibration["Rf"].value / factor
-    stiffness_corrected = calibration["kappa"].value / factor**2
-
-To correct a force trace, simply divide it by the correction factor::
-
-    corrected_force1x = f.force1x / factor
-
-.. note::
-
-    This coupling model neglects effects from the surface. It is intended for measurements performed at the center of the flowcell.
-
-.. note::
-
-    The model implemented here only supports beads that are aligned in the same plane.
-    It does not take a mismatch in the `z`-position of the beads into account.
-    In reality, the position in the focus depends on the bead radius and may be different for the two beads if they slightly differ in size :cite:`alinezhad2018enhancement` (Fig. 3).
-    At short bead-to-bead distances, such a mismatch would make the coupling less pronounced than the model predicts.
-
 Fast Sensors
 ------------
 

docs/tutorial/force_calibration/coupling.rst

@@ -0,0 +1,57 @@
+.. _bead_bead_tutorial:
+
+Active calibration with two beads far away from the surface
+-----------------------------------------------------------
+
+.. warning::
+
+    The implementation of the coupling correction models is still alpha functionality.
+    While usable, this has not yet been tested in a large number of different scenarios.
+    The API can still be subject to change *without any prior deprecation notice*!
+    If you use this functionality keep a close eye on the changelog for any changes that may affect your analysis.
+
+.. image:: figures/coupling_factors.png
+  :nbattach:
+
+When performing active calibration with two beads, we get a lower fluid velocity around the beads than we would with a single bead.
+This leads to a smaller voltage readout than expected and therefore a higher displacement sensitivity (microns per volt).
+Failing to take this into account results in a bias as shown below:
+
+.. image:: figures/coupling_errors.png
+  :nbattach:
+
+Pylake offers a function to calculate a correction factor to account for the lower velocity around the bead.
+
+.. note::
+
+    For more information on how these factors are derived, please refer to the :ref:`theory<bead_bead_theory>` section on this topic.
+
+Appropriate correction factors for oscillation in x can be calculated as follows::
+
+    factor = lk.coupling_correction_2d(dx=5.0, dy=0, bead_diameter=bead_diameter, is_y_oscillation=False)
+
+Here `dx` and `dy` represent the horizontal and vertical distance between the beads.
+Note that these refer to *center to center distances* (unlike the distance channel in Bluelake, which represents the bead surface to surface distance).
+Note that all three parameters have to be specified in the same spatial unit (meters or micron).
+The final parameter `is_y_oscillation` indicates whether the stage was oscillated in the y-direction.
+
+The obtained correction factor can be used to correct the calibration factors::
+
+    Rd_corrected = factor * calibration["Rd"].value
+    Rf_corrected = calibration["Rf"].value / factor
+    stiffness_corrected = calibration["kappa"].value / factor**2
+
+To correct a force trace, simply divide it by the correction factor::
+
+    corrected_force1x = f.force1x / factor
+
+.. note::
+
+    This coupling model neglects effects from the surface. It is intended for measurements performed at the center of the flowcell.
+
+.. note::
+
+    The model implemented here only supports beads that are aligned in the same plane.
+    It does not take a mismatch in the `z`-position of the beads into account.
+    In reality, the position in the focus depends on the bead radius and may be different for the two beads if they slightly differ in size :cite:`alinezhad2018enhancement` (Fig. 3).
+    At short bead-to-bead distances, such a mismatch would make the coupling less pronounced than the model predicts.

docs/tutorial/force_calibration/force_calibration.rst

@@ -17,7 +17,7 @@ Experimental considerations
 Core parameters
 """""""""""""""
 
-Calibration involves fitting a model to data.
+Calibration involves fitting a model to data acquired while the bead moves in the trap.
 This model relies on a number of parameters that have to be specified in order to get the correct
 calibration factors.
 The most important parameters are:
@@ -43,6 +43,9 @@ Using the hydrodynamically correct theory requires a few extra parameters: the d
 sample `rho_sample` and bead `rho_bead`. When `rho_sample` and `rho_bead` are not provided,
 Pylake uses values for water and polystyrene for the sample and bead density respectively.
 
+.. image:: figures/surface_calibration_workflow.png
+    :nbattach:
+
 Experiments near the surface
 """"""""""""""""""""""""""""
 
@@ -53,49 +56,80 @@ Since it can be challenging to determine this distance, it is recommended to use
 when calibrating near the surface, since active calibration makes calibration far less sensitive
 to mis-specification of the bead diameter, viscosity and distance to the surface.
 
-- For axial calibration the flag `axial=True` should be set.
-- In the case of a pre-characterized diode, the values for its parameters can be passed to
-  `fixed_alpha` and `fixed_diode`.
-- In the case of active calibration, it is mandatory to provide a nanostage signal, as well as a
-  guess of the driving frequency.
+Active calibration
+""""""""""""""""""
+
+In the case of active calibration, it is mandatory to provide a nanostage signal to `driving_data`,
+as well as a guess of the driving frequency to `driving_frequency_guess`. While active calibration
+is less sensitive to the exact values of the bead diameter, viscosity and height, it is more
+sensitive to dirt in the trap and needs to be corrected for :ref:`coupling<bead_bead_tutorial>`
+if more than one bead is used.
+
+.. image::coupling_errors.png
+  :nbattach:
 
 Technical considerations
 ************************
 
 Force detector
 """"""""""""""
 
-In addition to the model that describes the bead's motion, it is important to take into account the
-:ref:`characteristics of the force detector<diode_theory>` used to measure the data.
+It is important to take into account the :ref:`characteristics of the force detector<diode_theory>`
+used to measure the bead position.
 
-A silicon diode sensor is characterized by two parameters, a "relaxation factor" `alpha` and
-frequency `f_diode`.
-These parameters can either be fitted along with the other parameters or characterized independently.
+A silicon diode sensor imparts a filtering effect that can be characterized by two parameters,
+a "relaxation factor" `alpha` and frequency `f_diode`.
+These parameters can either be fitted along with the other parameters or characterized independently and fixed.
+InGaAs detectors are faster and do not exhibit this additional filtering effect at all.
+In C-Traps, the faster detectors are typically used for axial calibration (`z`).
+You can check whether a calibration came from a fast sensor by checking the
+:attr:`~lumicks.pylake.calibration.ForceCalibrationItem.fast_sensor` property.
 
 You can check whether Bluelake had to estimate parameters from the calibration
 data by checking the property :attr:`~lumicks.pylake.calibration.ForceCalibrationItem.fitted_diode`.
-When this property is set to true, it means that the diode parameters were not fixed during the fit.
+When this property is set to true, it means that the diode parameters were fitted (i.e. not fixed during the fit).
 
-When fitted, care must be taken that the corner frequency of the power spectrum `fc` is
+When a diode model is fitted, care must be taken that the corner frequency of the power spectrum `fc` is
 :ref:`lower than the estimated diode frequency<high_corner_freq>`.
 
+The model can sometimes abuse the diode model to fit aspects of the data phenomenologically that
+technically are not caused by the diode. For example, fitting a model that should have the
+hydrodynamically correct model enabled without hydrodynamic effects, the diode can sometimes
+partially "compensate" for the missing hydrodynamic effects. This makes the fit look good,
+but the calibration may still be biased. The converse is also true, when using diode model with
+fixed parameters, it is more critical to use the best possible model and ensure that the fit
+ranges and exclusion ranges are chosen appropriately. Any failure to fit the data will result in a
+bias in the calibration as the fitting procedure will try to change the corner frequency to
+compensate for the lack of fit.
+
+When performing a calibration, check the following:
+
+- Consider whether you are dealing with a fast-sensor. If so, set `fast_sensor` to `True`. In most systems, axial (`z`) detectors are fast, while lateral (`x` and `y`) detectors are not.
+- Are you using a pre-calibrated diode? If so, make sure you pass the diode parameters for that power to `fixed_alpha` and `fixed_diode`. Note that these parameters depend on the total laser power hitting the sensor.
+- When you are not fitting a diode model, make sure you use the hydrodynamically correct model where appropriate.
+- If you are fitting a diode model, make sure that the corner frequency is at least 1 kHz below the diode frequency.
+
 Fit range
 """""""""
 
-The fit range determines which section of the power spectrum is actually fit. Two things are important when choosing a fitting range:
+The fit range determines which section of the power spectrum is actually fit.
+Two things are important when choosing a fitting range:
 
 - The corner frequency should be clearly visible in the fitted range (frequency where the slope increases).
 - When working at low laser laser powers, it is possible that the noise floor becomes visible at higher frequencies. This noise floor should be excluded.
 
 Exclusion ranges
 """"""""""""""""
 
-
+Since the fitting routine is very sensitive to outliers, noise peaks must be excluded prior to fitting.
+To do this, provide a list of tuples specifying the minimum and maximum frequency range of each exclusion range to the `excluded_ranges` parameter.
 
 Blocking
 """"""""
 
-
+The `num_points_per_block` parameter controls how much the power spectrum is downsampled.
+Generally, this value should be chosen larger than `100`.
+Care must be taken if the corner frequency is very low.
 
 
 

docs/tutorial/force_calibration/index.rst

@@ -11,3 +11,4 @@ Find out about force calibration
     force_calibration
     low_level_api
     robust_fitting
+    coupling