fixups

docs/theory/force_calibration/diode.rst

@@ -1,8 +1,8 @@
+.. _diode_theory:
+
 Position sensitive detector
 ---------------------------
 
-.. _diode_theory:
-
 The previous section introduced the origin of the frequency spectrum of a bead in an optical trap.
 In reality, our measurement is affected by two processes:
 
@@ -22,11 +22,10 @@ Why is the bandwidth limited?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The high bandwidth of visible light detection of a silicon photodiode is achieved when incoming photons are absorbed in the so-called depletion layer of the diode.
-Unfortunately, silicon has an increased transparency at the near infra-red wavelength of the trapping laser
-What this means is that light penetrates deeper into the substrate of the diode, where it generates charge carriers in a different region of the diode.
-These charge carriers then have to diffuse to the depletion layer, which takes time.
+Unfortunately, silicon has an increased transparency at the near infra-red wavelength of the trapping laser.
+The result of this is that light penetrates deeper into the substrate of the diode, where it generates charge carriers in a different region of the diode.
+These charge carriers then have to diffuse back to the depletion layer, which takes time.
 As a result, a fraction of the signal has a much slower dynamic response (i.e. a lower bandwidth).
-In other words, a typical PSD is less sensitive to changes in signal at high frequencies.
 
 .. image:: figures/diode.png
   :nbattach:
@@ -37,11 +36,11 @@ This model is characterized by two numbers whose values depend on the incident l
 - A frequency `f_diode`, given in Hertz.
 - A unit-less relaxation factor `alpha` which reflects the fraction of light that is transmitted instantaneously.
 
+.. _high_corner_freq:
+
 High corner frequencies
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-.. _high_corner_freq:
-
 In literature, the diode parameters are frequently estimated simultaneously with the calibration data :cite:`berg2003unintended,hansen2006tweezercalib,berg2006power,tolic2006calibration,tolic2004matlab,berg2004power`.
 Unfortunately, this can cause issues when calibrating at high powers.
 

docs/theory/force_calibration/hyco.rst

@@ -34,7 +34,7 @@ Fast sensor measurement
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 When fitting a power spectrum, one may ask the question, so why does the fit look good if the model is bad?
-The answer to this lies in the model that is used to capture the parasitic filtering effect.
+The answer to this lies in the model that is used to capture the :ref:`parasitic filtering effect<diode_theory>`.
 When the parameters of this model are estimated, what can happen is that they "hide" the mis-specification of the model.
 
 Fast detectors have the ability to respond much faster to incoming light resulting in no visible filtering effect in the frequency range we are fitting.

docs/tutorial/force_calibration/force_calibration.rst

@@ -25,14 +25,18 @@ Note that the viscosity of water strongly depends on :ref:`temperature<temperatu
 To find the viscosity of water at a particular temperature, Pylake uses :func:`~lumicks.pylake.viscosity_of_water` which implements the model presented in :cite:`huber2009new`.
 When omitted, this function will automatically be used to look up the viscosity of water for that particular temperature
 
+.. image:: figures/temperature_dependence.png
+  :nbattach:
+
 **Hydrodynamically correct model**
 
-For lateral calibration, it is recommended to use the hydrodynamically correct theory (setting
-`hydrodynamically_correct` to `True`) as it provides an improved model of the underlying
-physics (see :ref:`Hydrodynamically correct model`).
+For lateral calibration, it is recommended to use the
+:ref:`hydrodynamically correct theory<hydro_model_theory>` by setting `hydrodynamically_correct` to
+`True`) as it provides an improved model of the underlying physics.
 For small beads (< 1 micron) the differences will be small, but for larger beads substantial
 differences can occur. There is only one exception to this recommendation, which is when the beads
 are so close to the flowcell surface (0.75 x diameter) that this model becomes invalid.
+
 Using the hydrodynamically correct theory requires a few extra parameters: the density of the
 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.
@@ -44,9 +48,12 @@ Experiments near the surface
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When doing experiments near the surface, it is recommended to provide a `distance_to_surface`.
-This distance should be the center of the bead to the surface of the flowcell.
+This distance should be the distance from the center of the bead to the surface of the flowcell.
 Since it can be challenging to determine this distance, it is recommended to use active calibration
-when calibrating near the surface.
+when calibrating near the surface, since this makes calibration less sensitive to mis-specification
+of the bead diameter and height.
+
+
 
 
 
@@ -68,8 +75,9 @@ frequency `f_diode`. These parameters can either be estimated along with the oth
 characterized independently.
 When estimated, care must be taken that the corner frequency of the power spectrum `f_c` is
 :ref:`lower than the estimated diode frequency<high_corner_freq>`.
-You can check whether a calibration item used a fitted diode by checking the property
-`recalibrated.fitted_diode`.
+You can check whether a calibration item had to estimate parameters from the calibration
+data by checking the property `recalibrated.fitted_diode`.
+When this property is set to true, it means that the diode parameters were not fixed during the fit.
 
 .. warning::